"""Language configuration base class.

Centralizes project and language settings that were previously
scattered across plugin metadata, optimizer constructors, and
API config objects.  Each language package extends this with
language-specific fields (e.g. ``pytest_cmd`` for Python,
``node_args`` for JavaScript).

Follows the platform-libs pattern: ``AbstractCloudConfiguration``
is a base dataclass that each provider (Azure, Minikube) extends
with provider-specific fields.  Here, ``LanguageConfiguration``
is the base that each language extends.

Usage from a language package::

    from codeflash_core import LanguageConfiguration

    @attrs.frozen
    class PythonConfiguration(LanguageConfiguration):
        pytest_cmd: str = "pytest"
        coverage_threshold: float = 0.8
"""

from __future__ import annotations

from typing import TYPE_CHECKING

import attrs

if TYPE_CHECKING:
    from pathlib import Path


@attrs.frozen
class LanguageConfiguration:
    """Base configuration for a language optimization session.

    Carries the settings that every language needs: where the
    project lives, where tests are, and how to interact with
    the AI service.  Language-specific packages subclass this
    and add their own fields.

    All fields are immutable after construction.  To change
    a setting, create a new instance via ``attrs.evolve``.
    """

    project_root: Path
    """Root directory of the project being optimized."""

    tests_root: Path
    """Directory containing the project's test suite."""

    test_framework: str
    """Test framework name: ``"pytest"``, ``"jest"``, ``"junit"``."""

    ignore_paths: tuple[Path, ...] = ()
    """Paths to exclude from function discovery and analysis."""

    api_key: str = attrs.field(default="", repr=False)
    """API key for the Codeflash AI service."""

    n_candidates: int = 5
    """Number of optimization candidates to request per function."""

    ai_timeout: float = 120.0
    """Timeout in seconds for AI service requests."""
