"""Pydantic schemas for mission generation LLM structured output.

These models define the expected structure of the LLM's mission response.
Field descriptions guide the model to produce appropriate output.
"""

# ruff: noqa: E501 (Field descriptions are long to guide LLM output)
from __future__ import annotations

from pydantic import BaseModel, Field


class MissionFileRefResponse(BaseModel):
    """A file reference within a mission.

    The LLM identifies specific files and line ranges relevant to the mission.
    """

    file_path: str = Field(
        description=(
            "Relative path to a source file relevant to this mission. "
            "Must be a valid path from the analyzed codebase. "
            "Example: 'src/handlers/auth.py'"
        )
    )
    line_start: int | None = Field(
        default=None,
        description=(
            "1-indexed starting line number for the relevant code section. "
            "Set to null if the entire file is relevant. "
            "Example: 42"
        ),
    )
    line_end: int | None = Field(
        default=None,
        description=(
            "1-indexed ending line number for the relevant code section (inclusive). "
            "Set to null if the entire file is relevant. "
            "Example: 67"
        ),
    )
    description: str = Field(
        description=(
            "Brief explanation of why this file/section is relevant to the mission. "
            "1-2 sentences. Example: 'Contains the login handler that validates credentials.'"
        )
    )


class MissionItemResponse(BaseModel):
    """A single investigation mission.

    Each mission is a focused task that helps the user understand a specific
    aspect of the codebase.
    """

    title: str = Field(
        description=(
            "Film Noir themed mission title. Use detective/investigation language. "
            "Examples: 'The Password Vault', 'Shadows in the Login Flow', "
            "'Following the Data Trail'. Make it evocative and memorable."
        )
    )
    title_plain: str = Field(
        description=(
            "Plain English title without theming. Used for prerequisites and display. "
            "Examples: 'Understand Password Storage', 'Trace Login Authentication', "
            "'Follow Data from Input to Storage'. Clear and descriptive."
        )
    )
    description: str = Field(
        description=(
            "2-3 sentence description of what the user will investigate and learn. "
            "Frame it as an investigation task. Be specific about files/concepts involved. "
            "Example: 'Investigate how user passwords are hashed and stored. "
            "Start in auth.py and trace the password handling through the encryption layer.'"
        )
    )
    difficulty: str = Field(
        description=(
            "Mission difficulty: 'quick' (10-15 min), 'medium' (20-30 min), "
            "or 'deep_dive' (30-45 min). "
            "Quick missions are single-file focused. Medium spans 2-3 files. "
            "Deep dives involve multiple modules or complex patterns."
        )
    )
    completion_condition: str = Field(
        description=(
            "Clear, verifiable condition for completing this mission. "
            "User should know when they're done. "
            "Example: 'You can explain how the JWT tokens are generated and validated.'"
        )
    )
    security_tag: bool = Field(
        description=(
            "True if this mission involves security-relevant code "
            "(auth, encryption, validation, secrets, permissions). "
            "Security missions are highlighted for users."
        )
    )
    standard_tag: str | None = Field(
        default=None,
        description=(
            "Optional tag for missions that relate to coding standards or best practices. "
            "Examples: 'error_handling', 'testing', 'documentation', 'type_safety'. "
            "Set to null if not applicable."
        ),
    )
    narrative_intro: str = Field(
        description=(
            "Film Noir themed opening line to set the mood. "
            "Example: 'The old safe in the corner caught your eye...'"
        )
    )
    narrative_outro: str = Field(
        description=(
            "Film Noir themed closing line after completion. "
            "Example: 'Another case closed. The passwords were secure after all.'"
        )
    )
    file_refs: list[MissionFileRefResponse] = Field(
        description=(
            "1-5 file references relevant to this mission. "
            "Each reference includes the file path, optional line range, "
            "and a description of why it's relevant."
        )
    )
    module_index: int = Field(
        description=(
            "Index (0-based) into the briefing's module list. "
            "Identifies which module this mission primarily relates to. "
            "Use 0 if unsure or if the mission spans multiple modules."
        )
    )
    prerequisite_titles: list[str] = Field(
        default_factory=list,
        description=(
            "List of title_plain values for missions that must be completed first. "
            "Only include missions within this same category. "
            "Leave empty for root missions (no prerequisites). "
            "Maximum 2 prerequisites per mission."
        ),
    )


class ChainResponse(BaseModel):
    """A chain of related missions to be completed in sequence.

    Chains group missions that tell a story or build on each other
    in a natural learning progression.
    """

    name: str = Field(
        description=(
            "Film Noir themed chain name. "
            "Example: 'The Authentication Trilogy', 'The Database Chronicles'"
        )
    )
    name_plain: str = Field(
        description=(
            "Plain English chain name. "
            "Example: 'Authentication Flow', 'Database Layer Investigation'"
        )
    )
    description: str = Field(
        description=(
            "1-2 sentence description of what this chain explores together. "
            "Example: 'Follow the complete authentication flow from login to session.'"
        )
    )
    mission_titles: list[str] = Field(
        description=(
            "Ordered list of title_plain values for missions in this chain. "
            "Missions are completed in this order. "
            "Minimum 2 missions, maximum 5."
        )
    )


class CategoryMissionsResponse(BaseModel):
    """Complete mission generation response for one investigation category.

    Contains all missions and chains for a single category.
    """

    missions: list[MissionItemResponse] = Field(
        description=(
            "3-8 missions for this category. "
            "Include a mix of quick, medium, and deep_dive difficulties. "
            "At least 1-2 missions must have empty prerequisite_titles (root missions). "
            "Cover different aspects of the category within this codebase."
        )
    )
    chains: list[ChainResponse] = Field(
        default_factory=list,
        description=(
            "0-3 chains grouping related missions. "
            "Chains are optional but help organize related investigations. "
            "Each mission can appear in at most one chain."
        ),
    )
    warnings: list[str] = []
