"""
Pipeline tag conventions.

The backend stores a tag as an opaque string and validates it against an allowed
character set. The web console encodes a tag's color into the string itself
as a suffix that character set permits: the visible name, then a ``|`` separator,
then a six-digit ``rrggbb`` hex color -- e.g. ``"prod|ef4444"``. The suffix
is optional, so a bare ``"prod"`` is an uncolored tag; ``"prod|ef4444"`` and
``"prod|22c55e"`` are considered a tag collision which can but should not occur.

To stay consistent with the web console, the SDK treats a tag's *display name* --
its name with any color suffix removed -- as the tag's identity, and enforces two
invariants whenever a pipeline's tags are written:

* **Variant exclusivity.** A pipeline carries at most one tag per display name.
  When a list holds several color variants of the same name, the last one wins.
* **Lexicographic order.** Tags are sorted lexicographically by the SDK
  before sending to the API server.
"""

import re
from typing import Iterable, List

# A tag's color suffix: a ``|`` followed by exactly six lowercase hex digits at
# the end of the string (no ``#``, which the backend's tag character set
# disallows). Lowercase is the one canonical form; uppercase hex is therefore
# not recognized as a color and stays part of the name.
# Recognized only in this exact form, so a name that itself contains
# ``|`` (without a trailing color) keeps its full text.
_COLOR_SUFFIX = re.compile(r"\|[0-9a-f]{6}$")


def tag_display_name(tag: str) -> str:
    """Return a tag's visible text: its name with any color suffix removed."""

    return _COLOR_SUFFIX.sub("", tag)


def _normalize_tags(tags: Iterable[str]) -> List[str]:
    """
    Collapse color variants of the same tag and sort the result.

    Tags that share a display name are deduplicated, keeping the last occurrence,
    and the survivors are returned in lexicographic order. The color suffix that
    encodes a tag's color is preserved.
    """

    by_display_name: dict[str, str] = {}
    for tag in tags:
        by_display_name[tag_display_name(tag)] = tag
    return sorted(by_display_name.values())