"""Pydantic schemas for LLM structured output.

These models define the expected structure of the LLM's briefing 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 ModuleDescription(BaseModel):
    """Description of a detected module cluster.

    The LLM assigns a meaningful name and description to each module
    based on the files it contains and their purpose.
    """

    name: str = Field(
        description=(
            "A concise, descriptive name for this module cluster. "
            "Use 2-4 words that describe its purpose (e.g., 'Authentication Handlers', "
            "'Database Models', 'CLI Commands'). Avoid generic names like 'Utils' or 'Helpers'."
        )
    )
    description: str = Field(
        description=(
            "A 1-2 sentence description of what this module does and its role "
            "in the codebase. Focus on the domain purpose, not implementation details."
        )
    )
    security_relevant: bool = Field(
        description=(
            "True if this module handles security-sensitive operations such as "
            "authentication, authorization, encryption, secrets, or data validation. "
            "False for business logic, UI, testing, or utility code."
        )
    )


class BriefingResponse(BaseModel):
    """Structured response from the LLM briefing generation.

    This model captures the complete codebase analysis in a structured format
    that can be persisted and used for mission generation.
    """

    summary: str = Field(
        description=(
            "A plain-language overview of what the codebase does, its purpose, "
            "and how it is organized. Write 3-5 paragraphs covering: "
            "(1) The application's main purpose and domain, "
            "(2) High-level architecture and key components, "
            "(3) Entry points and how users interact with it, "
            "(4) Notable patterns or conventions used, "
            "(5) Any unique or interesting aspects of the codebase. "
            "Write in a professional but accessible tone. Avoid marketing language."
        )
    )
    tech_stack: list[str] = Field(
        description=(
            "List of technologies, frameworks, libraries, and tools used. "
            "Include specific versions if mentioned. Order by importance/relevance. "
            "Examples: 'Python 3.10', 'FastAPI', 'SQLite', 'Pydantic', 'pytest'. "
            "Include both runtime and development dependencies."
        )
    )
    security_posture: str = Field(
        description=(
            "Assessment of the codebase's security posture. Describe: "
            "(1) Any security-relevant patterns found (auth, encryption, etc.), "
            "(2) Potential concerns from the security scan results, "
            "(3) Notable security practices observed. "
            "If no security issues were found, state 'No significant security concerns "
            "identified during analysis.' Be specific about what was checked."
        )
    )
    modules: list[ModuleDescription] = Field(
        description=(
            "A description for each detected module cluster. "
            "The number of entries must match the number of modules provided in the input. "
            "Assign meaningful names based on the files in each cluster and their purpose."
        )
    )
