"""Utilitaires de normalisation et de traitement du texte.

Ce module centralise les transformations de texte partagées par plusieurs
couches du pipeline ``pronote-sync`` (sources, synchronisation) afin que les
modules de logique de domaine ne dépendent pas d'adaptateurs concrets.
"""

from __future__ import annotations

import re
import unicodedata

__all__ = ["normalize_subject"]


def normalize_subject(subject: str) -> str:
    """Normalise une matière pour le matching déterministe.

    Applique la normalisation Unicode NFKC, unifie les espaces (y compris
    tabulations et espaces insécables), supprime la ponctuation et met la
    chaîne en minuscules. Deux représentations visuellement identiques d'une
    même matière produisent ainsi la même forme normalisée.

    :param subject: La matière brute.
    :return: La forme normalisée (NFKC, espaces unifiés, sans ponctuation, minuscule).
    :rtype: str
    """
    normalized = unicodedata.normalize("NFKC", subject)
    normalized = re.sub(r"\s+", " ", normalized).strip()
    normalized = re.sub(r"[^\w\s]", "", normalized)
    normalized = re.sub(r"\s+", " ", normalized).strip()
    return normalized.lower()