"""Type stubs for doc-forge core model objects."""

from typing import Any, Dict, List, Optional, Protocol
from pathlib import Path

class DocObject:
    """Represents a Python documentation object (class, function, variable, etc.)."""
    
    name: str
    kind: str
    path: str
    signature: Optional[str]
    docstring: Optional[str]
    members: Dict[str, 'DocObject']
    
    def __init__(self, name: str, kind: str, path: str, signature: Optional[str] = None, docstring: Optional[str] = None) -> None: ...
    
    def add_member(self, member: 'DocObject') -> None: ...
    
    def get_member(self, name: str) -> Optional['DocObject']: ...
    
    def is_private(self) -> bool: ...

class Module:
    """Represents a Python module in the documentation model."""
    
    path: str
    docstring: Optional[str]
    members: Dict[str, DocObject]
    
    def __init__(self, path: str, docstring: Optional[str] = None) -> None: ...
    
    def add_object(self, obj: DocObject) -> None: ...
    
    def get_object(self, name: str) -> Optional[DocObject]: ...
    
    def get_public_objects(self) -> List[DocObject]: ...

class Project:
    """Root container for all documentation in a project."""
    
    name: str
    version: Optional[str]
    modules: Dict[str, Module]
    nav: 'Navigation'
    
    def __init__(self, name: str, version: Optional[str] = None) -> None: ...
    
    def add_module(self, module: Module) -> None: ...
    
    def get_module(self, path: str) -> Optional[Module]: ...
    
    def get_all_modules(self) -> List[Module]: ...

class Navigation:
    """Navigation structure derived from project modules."""
    
    entries: List['NavEntry']
    
    def __init__(self) -> None: ...
    
    def add_entry(self, entry: 'NavEntry') -> None: ...
    
    def get_entry(self, title: str) -> Optional['NavEntry']: ...

class NavEntry:
    """Single navigation entry linking to a module."""
    
    title: str
    module: str
    
    def __init__(self, title: str, module: str) -> None: ...

class DocRenderer(Protocol):
    """Protocol for documentation renderers."""
    
    name: str
    
    def generate_sources(self, project: Project, out_dir: Path) -> None: ...
    
    def build(self, config: 'RendererConfig') -> None: ...
    
    def serve(self, config: 'RendererConfig') -> None: ...

class RendererConfig:
    """Base configuration for renderers."""
    
    out_dir: Path
    project: Project
    
    def __init__(self, out_dir: Path, project: Project) -> None: ...

class GriffeLoader:
    """Loads Python modules using Griffe introspection."""
    
    def __init__(self) -> None: ...
    
    def load_project(self, module_paths: List[str]) -> Project: ...
    
    def load_module(self, path: str) -> Module: ...

class MCPExporter:
    """Exports documentation model to MCP JSON format."""
    
    def __init__(self) -> None: ...
    
    def export(self, project: Project, out_dir: Path) -> None: ...

class MCPServer:
    """Live MCP server for documentation queries."""
    
    def __init__(self, project: Project) -> None: ...
    
    def start(self, host: str = "localhost", port: int = 8080) -> None: ...
    
    def stop(self) -> None: ...