class HeadingNode(MarkdownNode):
    """ Represents a heading node in the markdown tree structure.

    Use accessor functions to read properties.
    """
    def __init__(
        self,
        block: HeadingBlock | HeaderBlock,
        parent: "HeadingNode | None" = None,
    ):
        # this can only happen if type checks were ignored
        assert isinstance(
            block, (HeadingBlock, HeaderBlock)
        ), f"Invalid block type: {type(block)}"
        # type checker complains here, but it will enforce the
        # type at any subsequent access to the block data member,
        # simulating covariance
        self.block: HeadingBlock | HeaderBlock  # type: ignore
        super().__init__(block, parent)

    # Overrides
    @override
    def is_heading_node(self) -> bool:
        return True

    # Copy
    def naked_copy(self) -> 'HeadingNode':
        """Make a deep copy of this node and take it off the tree"""
        block_copy: HeadingBlock | HeaderBlock = (
            self.block.model_copy(deep=True)
        )
        new_node = HeadingNode(block_copy)
        new_node.metadata = copy.deepcopy(self.metadata)
        if self.metadata_block:
            new_node.metadata_block = self.metadata_block.model_copy(
                deep=True
            )

        return new_node

    def node_copy(self) -> 'HeadingNode':
        """Make a deep copy of this node, maintaining links to
        children. This creates a new branch root with reference to
        all children, but detached from the upper tree.
        """

        newnode = self.naked_copy()
        newnode.children = self.children
        return newnode

    def tree_copy(self) -> 'HeadingNode':
        """Make a deep copy of this node and its children
        (copy subtree)"""

        new_node = self.naked_copy()

        for child in self.children:
            child_copy = child.tree_copy()
            child_copy.parent = new_node
            new_node.children.append(child_copy)

        return new_node

    # Utility functions to retrieve basic properties
    def get_text_children(self) -> list['TextNode']:
        """Returns a list of children text nodes."""
        return [n for n in self.children if isinstance(n, TextNode)]

    def get_heading_children(self) -> list['HeadingNode']:
        """Returns a list of children heading nodes."""
        return [
            n for n in self.children if isinstance(n, HeadingNode)
        ]

    def heading_level(self) -> int:
        """Returns an integer for the heading level. The root
        node, if corresponding to a markdown header, has level 0."""
        if isinstance(self.block, HeadingBlock):
            return self.block.level
        return 0  # Root level for HeaderBlock

    def get_content(self) -> str:
        """Returns the title of the heading represented by the node"""
        if self.is_header_node():
            return self.get_metadata_string_for_key('title') or ""
        else:
            return str(self.block.get_content())

    def set_content(self, content: str) -> None:
        """Sets the text of the title of the heading represented
        by the node
        """
        match self.block:
            case HeaderBlock():
                self.set_metadata_for_key('title', content)
            case HeadingBlock():
                self.block.content = content

    def get_info(self, indent: int = 0) -> str:
        """
        Reports information about a node, including its type, content,
        and metadata.

        Args:
            indent: The indentation level for pretty printing
        """
        import yaml

        indent_str = "  " * indent

        # Collect block type and content
        info: str
        if self.is_header_node():
            info = "Header node:\n"
            info += f"{indent_str}Content: {self.get_content()}"
        else:
            info = "Heading node\n"
            info += (
                f"{indent_str}Heading (Level {self.heading_level()}):"
                + f" {self.get_content()}"
            )

        # Info on children
        if self.children:
            info += f"\nHas {self.count_children()} children, of "
            info += (
                f"which {len(self.get_text_children())} are "
                + "text children"
            )
        else:
            info += "\nNode with no children"

        # Collect metadata
        if self.metadata:
            info += (
                f"\n{indent_str}Metadata:"
                + f"\n{yaml.safe_dump(self.get_metadata())}"
            )

        if not info[-1] == '\n':
            info += "\n"
        return info

    def add_child(self, child_node: MarkdownNode) -> None:
        """
        Add a child node to this node.

        Args:
            child_node: The node to add as a child

        Note:
            one cannot add a heading node with a level equal or higher
            than that of the parent node. The level of the heading
            node is adjusted downwards automatically. Beyond the 
            lowest heading level, a text node is added.
        """
        if isinstance(child_node, HeadingNode):
            if self.heading_level() == LOWEST_HEADING_LEVEL:
                self.children.append(
                    TextNode.from_content(
                        content="#" * (LOWEST_HEADING_LEVEL + 1) + " "
                        + child_node.get_content(),
                        metadata=child_node.metadata,
                        parent=self,
                    )
                )
                return
            elif child_node.heading_level() <= self.heading_level():
                new_node = HeadingNode(
                    block=HeadingBlock(
                        level=self.heading_level() + 1,
                        content=child_node.get_content(),
                    )
                )
                new_node.metadata = child_node.metadata
                new_node.metadata_block = MetadataBlock(
                    content=child_node.metadata
                )
                child_node = new_node

        child_node.parent = self
        self.children.append(child_node)

class MarkdownNode(ABC):
    """
    Represents a node in the markdown tree structure.

    Each node contains a markdown block (heading or text), a reference
    to its parent, a list of children, and associated metadata. Both
    heading and text blocks have textual content.

    Use accessor functions to read properties of the node:

    - get_metadata()/fetch_metadata()
    - get_metadata_for_key()/fetch_metadata_for_key()
    - get_metadata_string_for_key()/fetch_metadata_string_for_key()

    The names of the functions indicate use:

    - get_* - node's own metadata
    - fetch_* - with inheritance
    - *_string_* - returns string representation
    """

    def __init__(
        self, block: Block, parent: 'HeadingNode | None' = None
    ):
        """
        Initialize a new MarkdownNode.

        Args:
            block: The original block (heading or text)
            parent: The parent node (None for root)
        """
        self.block: Block = block  # Original block
        self.parent: 'HeadingNode | None' = parent  # Parent node
        self.children: list['MarkdownNode'] = []  # Child nodes
        self.metadata: MetadataDict = {}  # Associated metadata
        # Original metadata block. This is a private immutable data
        # member that is used at serialization to reconstitute the
        # original markdown. Changes in self.metadata will be
        # incorporated in the original metadata block when the block
        # is serialized.
        self.metadata_block: HeaderBlock | MetadataBlock | None = None

    # Copy
    @abstractmethod
    def naked_copy(self) -> Self:
        """Make a deep copy of this node and take it off the tree."""
        pass

    @abstractmethod
    def node_copy(self) -> Self:
        """Make a copy of this node, but keep links to children."""
        pass

    @abstractmethod
    def tree_copy(self) -> Self:
        """Make a deep copy of this node and its children
        (copy subtree)."""
        pass

    # Utility functions to retrieve basic properties
    def is_header_node(self) -> bool:
        """A node initialized from a header block."""
        return self.metadata_block is not None and isinstance(
            self.metadata_block, HeaderBlock
        )

    def is_root_node(self) -> bool:
        """A node w/o parents, not necessarily a header."""
        return self.parent is None

    def is_text_node(self) -> bool:
        "Is this a TextNode"
        return False

    def is_heading_node(self) -> bool:
        "Is this a HeadingNode"
        return False

    @abstractmethod
    def get_text_children(self) -> list['TextNode']:
        pass

    @abstractmethod
    def get_heading_children(self) -> list['HeadingNode']:
        pass

    def get_parent(self) -> 'HeadingNode | None':
        return self.parent

    def count_children(self) -> int:
        return len(self.children)

    @abstractmethod
    def heading_level(self) -> int | None:
        pass

    # Content and metadata
    @abstractmethod
    def get_content(self) -> str:
        """Returns text of headings or of text nodes."""
        pass

    @abstractmethod
    def set_content(self, content: str) -> None:
        """Set text of headings or of text nodes."""
        pass

    def has_metadata_key(
        self,
        key: str,
        inherit: bool = False,
        include_header: bool = False,
    ) -> bool:
        if inherit:
            return (
                self.fetch_metadata_for_key(key, include_header)
                is not None
            )
        return bool(self.metadata) and (key in self.metadata)

    def get_metadata(self, key: str | None = None) -> MetadataDict:
        """
        Get the metadata of the current node. For the header node,
        the document header is the metadata.

        Returns:
            a conformant dictionary.
        """
        if not key:
            return copy.deepcopy(self.metadata)
        elif self.metadata and key in self.metadata:
            return {key: self.metadata[key]}
        return {}

    def get_metadata_for_key(
        self, key: str, default: MetadataValue = None
    ) -> MetadataValue:
        """
        Get the key value in the metadata of the current node. For the
        root node, the header value for that key is returned.

        Args:
            key: the key for which the metadata is searched
            default: a default value if the key is absent

        Returns:
            the key value, or a default value if the key is not
                found (None if no default specified).
        """
        if key in self.metadata:
            return self.metadata[key]
        return default

    def get_metadata_string_for_key(
        self, key: str, default: str | None = None
    ) -> str | None:
        """
        Get the string representation of the key value in the
        metadata of the current node. If the value is a dict
        of list, return None. If the key is not present, return
        a default value. For the root node, the header value for
        that key is returned.

        Args:
            key: the key for which the metadata is searched
            default: a default value if the key is absent

        Returns:
            the key value, a default value if the key is not
                found (None if no default specified). If the value
                is not a primitive value of the int, float, str, or
                bool type, returns None.
        """
        if key in self.metadata:
            value: MetadataValue = self.metadata[key]
            if is_metadata_primitive(value):
                return str(value)
            else:
                return None
        return default

    def set_metadata_for_key(
        self, key: str, value: MetadataValue
    ) -> None:
        """Set the metadata value at key of the current node.

        Args:
            key: the key where the value should be set
            value: the metadata value
        """
        self.metadata[key] = value

    def fetch_metadata(
        self, key: str | None = None, include_header: bool = True
    ) -> MetadataDict:
        """
        Returns the effective metadata for this node by traversing up
        the tree if necessary to find inherited metadata. The metadata
        are those of the first node with metadata. If a key is given,
        only a dictionary with that key will be returned. If
        include_header is False, the header node is not considered.

        Args:
            key: the key for which the metadata is searched
            include_header: if the header metadata should be included
                in the search

        Returns:
            A dictionary giving the effective metadata for this node
        """

        if not key:
            if self.metadata:
                if not include_header and self.is_header_node():
                    return {}
                return self.metadata.copy()
            elif self.parent:
                return self.parent.fetch_metadata(
                    None,
                    include_header,
                )
            return {}
        else:
            value = self.fetch_metadata_for_key(key, include_header)
            return {key: value} if value else {}

    def fetch_metadata_for_key(
        self,
        key: str,
        include_header: bool = True,
        default: MetadataValue = None,
    ) -> MetadataValue:
        """
        Returns the value for a specific metadata key by traversing up
        the tree if necessary to find inherited metadata. If
        include_header is False, the header node is not considered.

        This function extends the concept of metadata inheritance to
        look for a specific key in the node's metadata or its
        ancestors' metadata.

        Args:
            key: The specific metadata key to look for
            include_header: If to include the header in the search
            default: the value to return if the key is not found

        Returns:
            The value for the specified key, or a default value if not
            found in the node or any of its ancestors (or None if no
            default was specified).
        """

        if not key:
            return default

        if self.metadata and key in self.metadata:
            if not include_header and self.is_header_node():
                return default
            return self.metadata[key]
        elif self.parent:
            return self.parent.fetch_metadata_for_key(
                key, include_header, default
            )
        return default

    def fetch_metadata_string_for_key(
        self,
        key: str,
        include_header: bool = True,
        default: str | None = None,
    ) -> str | None:
        """
        Returns the string representation of the value of a specific
        metadata key by traversing up the tree if necessary to find
        inherited metadata. If the key is not present, return a
        default value. If the key is a dict or list, return None. If
        include_header is False, the header node is not considered.

        This function extends the concept of metadata inheritance to
        look for a specific key in the node's metadata or its
        ancestors' metadata.

        Args:
            key: The specific metadata key to look for
            include_header: If to include the header in the search
            default: the value to return if the key is not found

        Returns:
            The value for the specified key, or a default value if not
            found in the node or any of its ancestors (or None if no
            default was specified). If the value is not a primitive
            value of the int, float, str, or bool type returns None.
        """

        if not key:
            return default

        if self.metadata and key in self.metadata:
            if not include_header and self.is_header_node():
                return default
            return self.get_metadata_string_for_key(key)
        elif self.parent:
            return self.parent.fetch_metadata_string_for_key(
                key, include_header, default
            )
        return default

    def as_dict(
        self, inherit: bool = False, include_header: bool = True
    ) -> NodeDict:
        """
        Return a dictionary representation of the node.

        Args:
            inherit: if True, the metadata of the first parent with
                metadata
            include_header: if False, the header is not considered as
                a metadata source.

        Returns: a dictionary with keys 'content' and
        'metadata'.
        """
        if not inherit:
            return {
                'content': self.get_content(),
                'metadata': self.get_metadata(),
            }
        else:
            return {
                'content': self.get_content(),
                'metadata': self.fetch_metadata(None, include_header),
            }

    @abstractmethod
    def get_info(self) -> str:
        """Return a string rpresentation of the node with info
        on its properties"""
        pass

class NodeDict(TypedDict):
    """A dictionary representation of a node.

    Fields:
        content (str): the string content of the node (the title for
            a heading node, the text of a text node)
        metadata (MetadataDict): the metadata
    """

    content: str
    metadata: MetadataDict

class TextNode(MarkdownNode):
    """Represents a text node in the markdown tree.

    User accessor functions to retrieve properties.
    """
    def __init__(
        self,
        block: TextBlock | ErrorBlock,
        parent: "HeadingNode | None" = None,
    ):
        # this can only happen if type checks were ignored
        assert isinstance(
            block, (TextBlock, ErrorBlock)
        ), f"Invalid block type: {type(block)}"
        # type checker complains here, but it will enforce the
        # type at any subsequent access to the block data member,
        # simulating covariance
        self.block: TextBlock | ErrorBlock  # type: ignore
        super().__init__(block, parent)

    @staticmethod
    def from_content(
        content: str,
        metadata: MetadataDict | None = None,
        parent: HeadingNode | None = None,
    ) -> 'TextNode':
        """Create a text node from content and metadata.

        Args:
            content: the text content of the node
            metadata: a dictionary with metadata (optional)
            parent: if not None, the parent heading of the node

        Returns: 
            a text node.    
        """
        newnode = TextNode(
            block=TextBlock.from_text(content), parent=parent
        )
        if metadata:
            newnode.metadata = metadata
        return newnode

    # Overrides
    @override
    def is_text_node(self) -> bool:
        return True

    # Copy
    def naked_copy(self) -> 'TextNode':
        """Make a deep copy of this node and take it off the tree"""
        block_copy: TextBlock | ErrorBlock = self.block.model_copy(
            deep=True
        )
        new_node = TextNode(block_copy)
        new_node.metadata = copy.deepcopy(self.metadata)
        if self.metadata_block:
            new_node.metadata_block = self.metadata_block.model_copy(
                deep=True
            )

        return new_node

    def node_copy(self) -> 'TextNode':
        """Make a deep copy of this node (same as naked_copy for
        TextNodes)."""

        return self.naked_copy()

    def tree_copy(self) -> 'TextNode':
        """Make a deep copy of this node"""

        # Copy self
        return self.naked_copy()

    # Utility functions to retrieve basic properties
    def get_text_children(self) -> list['TextNode']:
        """Always returns an empty list for text nodes."""
        return []  # Text nodes have no children

    def get_heading_children(self) -> list['HeadingNode']:
        """Always returns an empty list for text nodes."""
        return []  # Text nodes have no children

    def heading_level(self) -> None:
        """Returns None as text nodes have no level."""
        return None  # Text nodes don't have levels

    def get_content(self) -> str:
        """Returns the content of the markdown text represented by
        the node."""
        return self.block.get_content()

    def set_content(self, content: str) -> None:
        """Set the text content of the node.

        Args:
            content: the new text content.
        """
        self.block.content = content

    def get_metadata(self, key: str | None = None) -> MetadataDict:
        """
        Get the metadata of the current node. If the text node has no
        metadata, the metadata of the heading.

        Args:
            key: the key for the metadata value to retrieve. If None,
                the whole dictionary.

        Returns:
            a conformant dictionary.

        Note: 
            in most cases, text will be annotated at the heading 
            level, not at individual paragraphs. The metadata of text
            nodes overrides the default metadata from the heading.
        """
        if not key:
            return copy.deepcopy(self.metadata)
        elif self.metadata and key in self.metadata:
            return {key: self.metadata[key]}
        elif (
            self.parent is not None
            and self.parent.metadata
            and key in self.parent.metadata
        ):
            return {key: self.parent.metadata[key]}
        return {}

    def get_metadata_for_key(
        self, key: str, default: MetadataValue = None
    ) -> MetadataValue:
        """
        Get the key value in the metadata of the current node. If the
        key is not in the node, return the key of the heading.

        Args:
            key: the key for which the metadata is searched
            default: a default value if the key is absent

        Returns:
            the key value, or a default value if the key is not
                found (None if no default specified).

        Note: 
            in most cases, text will be annotated at the heading 
            level, not at individual paragraphs. The metadata of text
            nodes overrides the default metadata from the heading.
        """
        if key in self.metadata:
            return self.metadata[key]
        elif self.parent is not None and key in self.parent.metadata:
            return self.parent.metadata[key]
        return default

    def get_metadata_string_for_key(
        self, key: str, default: str | None = None
    ) -> str | None:
        """
        Get the string representation of the key value in the
        metadata of the current node. If the value is a dict
        of list, return None. If the key is not present, return
        a default value. If the key is not in the metadata,
        return the key value of the heading.

        Args:
            key: the key for which the metadata is searched
            default: a default value if the key is absent

        Returns:
            the key value, a default value if the key is not
                found (None if no default specified). If the value
                is not a primitive value of the int, float, str, or
                bool type, returns None.

        Note: 
            in most cases, text will be annotated at the heading 
            level, not at individual paragraphs. The metadata of text
            nodes overrides the default metadata from the heading.
        """
        if key in self.metadata:
            value: MetadataValue = self.metadata[key]
            if is_metadata_primitive(value):
                return str(value)
            else:
                return None
        elif self.parent is not None and key in self.parent.metadata:
            value: MetadataValue = self.parent.metadata[key]
            if is_metadata_primitive(value):
                return str(value)
            else:
                return None
        return default

    def set_metadata_for_key(
        self, key: str, value: MetadataValue
    ) -> None:
        """Set the metadata value at key of the current node.

        Args:
            key: the key where the value should be set
            value: the metadata value
        """
        self.metadata[key] = value

    def get_info(self, indent: int = 0) -> str:
        """
        Reports information about a node, including its type, content,
        and metadata.

        Args:
            indent: The indentation level for pretty printing
        """
        import yaml

        indent_str = "  " * indent

        # Collect block type and content
        info = "Text node"
        info += "\n" if self.get_parent() else " (freestanding)\n"

        content = self.get_content()
        if len(content) > 50:
            content = content[:47] + "..."
        if len(content) > 0:
            info += f"{indent_str}Text: {content}"
        else:
            info += "Placeholder text block for metadata"

        # Collect metadata
        if self.metadata:
            info += (
                f"\n{indent_str}Metadata:"
                + f"\n{yaml.safe_dump(self.metadata)}"
            )

        if not info[-1] == '\n':
            info += "\n"
        return info