#!/usr/bin/env python3
# Copyright: 2016, Maximiliano Curia <maxy@debian.org>
#
# License: ISC
#  Permission to use, copy, modify, and/or distribute this software for any
#  purpose with or without fee is hereby granted, provided that the above
#  copyright notice and this permission notice appear in all copies.
#  .
#  THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
#  REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
#  AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
#  INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
#  LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
#  OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
#  PERFORMANCE OF THIS SOFTWARE.

"""
Copyright interface and data contracts extracted from dep5.py

This module defines the interfaces and data structures that Copyright classes
must implement, enabling better separation of concerns and testing.
"""

from __future__ import annotations

import typing as t

from .core_types import Options
from .group_contracts import GroupProtocol
from .nodes import FileInfo
from .tree import RootInfo


@t.runtime_checkable
class CopyrightProtocol(t.Protocol):
    """
    Protocol defining the interface that all Copyright classes must implement.

    This protocol allows for different Copyright implementations while
    maintaining a consistent interface.
    """

    groups: list[GroupProtocol] | None

    @staticmethod
    def build(filetree: RootInfo, options: Options) -> CopyrightProtocol:
        """Build a Copyright instance from the given filetree and options."""
        ...

    def process(self, filetree: RootInfo) -> None:
        """Process the filetree to match files to copyright information."""
        ...

    def remove_misplaced_files(
        self, options: Options, assigned: set[FileInfo] | None = None
    ) -> None:
        """Remove files from groups where they no longer belong."""
        ...

    def get_group_dict(self, options: Options) -> dict[t.Any, t.Any]:
        """Get a dictionary of groups keyed by their group keys."""
        ...
