"""word_utils - Utility functions for validating a 5x5 Waffle game grid.

Author: YOUR_NAME
Version: THE DATE
"""

from colorama import Fore, Style, init
from file_utils import Cell, Grid

# Initialize colorama
init()


def is_solved(current: Grid, solution: Grid) -> bool:
    """Check if the current grid matches the solution.

    Args:
        current: Current grid state.
        solution: Solution grid state.

    Returns:
        True if all letters match (case-insensitive).
    """
    pass
    return True


def check_swap(first: str, second: str) -> str:
    """Check if a swap between two letters is valid.

    Rules:
    - Both inputs must be single alphabetic characters; otherwise return "invalid".
    - Letters are compared case-insensitively.
    - Valid swap letters must be within the range a-y (inclusive) except g, i, q, s are not allowed.
      If not, return "out of range".
    - If both checks pass, return "valid".

    Args:
        first: The first letter to check.
        second: The second letter to check.

    Returns:
        "valid", "invalid", or "out of range".
    """
    pass
    return "valid"


def cell_to_str(cell: Cell) -> str:
    """Render a single cell with borders and color using colorama.

    Valid colors are:
    - GREEN  -> brackets: [A]
    - YELLOW -> parentheses: (A)
    - RED    -> underscores: _A_
    - WHITE  -> spaces:  A used for empty cells.
    - If color is unrecognized, set the style to Style.RESET_ALL.
    At the end of your return string make sure to reset the style using Style.RESET_ALL.
    or you may bleed over to other printed text.

    Args:
        cell: A cell in the form [letter, color].

    Returns:
        The rendered string with borders and colored letter.
        Border characters will be colored the same as the letter.
    """
    pass
    return " "


def print_grid(grid: Grid) -> None:
    """Print a 5x5 grid with borders and colored letters using colorama.

    The function accepts either:
    - a flat list of 25 cells: [[letter, color], ...]
    Border mapping:
    - GREEN  -> brackets: [A]
    - YELLOW -> parentheses: (A)
    - RED    -> underscores: _A_
    Colors applied to the letter itself using colorama Fore colors.
    ValueError should return: "grid must be a flat list of 25 cells or a 5x5 nested list")"
    if the grid is not valid.
    You will also print the a-y indexes to the right of the grid for reference for the text
    based version of the game.
    Sample output for initial starter.txt file :
    [M] _E_ (V) (A) [E]    a b c d e
    _R_  _  (R)  _  (S)    f   h   j
    (E) _P_ [U] (T) _U_    k l m n o
    _S_  _  (A)  _  (A)    p   r   t
    [L] [A] (E) (S) [L]    u v w x y

    Args:
        grid (list): A flat list of 25 cells or a nested 5x5 list.

    Raises:
        ValueError: If the grid is not a flat list of 25 cells or a 5x5 nested list.
    """
    pass


def update_grid(current: Grid, solution: Grid) -> Grid:
    """Validate a current flat 5x5 grid against the solution grid.

    You should check both lists are instances of Grid type.
    Otherwise raise ValueError with message: "current and solution must be lists".
    Also make sure they are 25 cells in length or
    return a ValueError message: current and solution must be flat lists of 25 cells
    Both `current` and `solution` must be flat lists of 25 cells where each
    cell is at least [letter, color]. This function compares letters from
    `current` to `solution` and returns a NEW flat list of 25 cells where the
    second element (color) is set to one of: 'GREEN', 'YELLOW', or 'RED'.

    Rules:
    - If current letter equals solution letter at the same index -> GREEN.
    - Else if current letter appears in the same row or same column of the
      solution grid (and hasn't been "used up" by other GREEN/YELLOW matches) -> YELLOW.
    - Else -> RED.

    Letter comparisons are case-insensitive. The returned cells will preserve
    the original current letter (unchanged) and any extra element (e.g. raw)
    after the color if present.

    Args:
        current: flat list of 25 cells, each cell [letter, color, ...].
        solution: flat list of 25 cells, each cell [letter, color, ...].

    Returns:
        New flat list of 25 cells with updated colors.

    Raises:
        ValueError: if inputs are not lists of length 25.
    """
    # You will need to create helper functions that this function calls to break down your solution.
    raise ValueError("not implemented")
    return []


def swap_cells(first: str, second: str, grid: Grid) -> Grid:
    """Swap two cells in a flat 5x5 grid using letter indices.

    The positions are specified by single-letter indices 'a'..'y' (mapping
    to positions 0..24). This function calls `check_swap(first, second)` and
    only performs the swap if that returns "valid". If the swap is not
    allowed the function returns the string result from `check_swap`.

    Other ValueErrors include:
    1) if the grid is not 25 cells long or
    if the grid is not a list type -> "grid must be a flat list of 25 cells"
    2) If first or second are not in range of 0-24 index value -> "out of range"
    3) ValueError from check_swap if anything there shows up other than "valid".

    Args:
        first (str): letter index for the first position (e.g. 'a').
        second (str): letter index for the second position (e.g. 'b').
        grid (list): flat list of 25 cells to operate on.

    Returns:
        A new flat list with the two cells swapped if successful,
        otherwise returns the check_swap error string.

    Raises:
        ValueError: If any of the arguments are invalid.
    """
    raise ValueError("not implemented")
    return []


if __name__ == "__main__":
    # Additional test code can go here.
    pass