"""
# Summary

Documentation model representing a project.

This module defines the `Project` class, the top-level container used by
doc-forge to represent a documented codebase. A `Project` aggregates multiple
modules and provides access to them through a unified interface.
"""

from typing import Dict, Iterable

from docforge.models.module import Module


class Project:
    """
    Representation of a documentation project.

    A `Project` serves as the root container for all modules discovered during
    introspection. Each module is stored by its dotted import path.

    Attributes:
        name (str):
            Name of the project.

        modules (Dict[str, Module]):
            Mapping of module paths to `Module` instances.
    """

    def __init__(self, name: str) -> None:
        """
        Initialize a Project instance.

        Args:
            name (str):
                Name used to identify the documentation project.
        """
        self.name = name
        self.modules: Dict[str, Module] = {}

    def add_module(self, module: Module) -> None:
        """
        Register a module in the project.

        Args:
            module (Module):
                Module instance to add to the project.
        """
        self.modules[module.path] = module

    def get_module(self, path: str) -> Module:
        """
        Retrieve a module by its dotted path.

        Args:
            path (str):
                Fully qualified dotted module path (for example `pkg.module`).

        Returns:
            Module:
                The corresponding `Module` instance.

        Raises:
            KeyError:
                If the module does not exist in the project.
        """
        return self.modules[path]

    def get_all_modules(self) -> Iterable[Module]:
        """
        Return all modules contained in the project.

        Returns:
            Iterable[Module]:
                An iterable of `Module` instances.
        """
        return self.modules.values()

    def get_module_list(self) -> list[str]:
        """
        Return the list of module import paths.

        Returns:
            list[str]:
                A list containing the dotted paths of all modules in the project.
        """
        return list(self.modules.keys())