#!/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

import debian.copyright as dc

from decopy.common.core_types import LicenseRegistry, Options
from decopy.fstree.nodes import FileInfo
from decopy.fstree.tree import RootInfo
from decopy.grouping.group_contracts import GroupProtocol


@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
    registry: LicenseRegistry

    @property
    def header(self) -> dc.Header:
        """The document header (read-only; consumers only read it)."""
        ...

    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."""
        ...
