"""
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: Name of the project.
        modules: Mapping of module paths to ``Module`` instances.
    """

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

        Args:
            name: 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 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: Fully qualified dotted module path (for example ``pkg.module``).

        Returns:
            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:
            An iterable of ``Module`` instances.
        """
        return self.modules.values()

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

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