"""
Nom du script : helpers.py
Chemin : /gitlab-bridge/app/utils/helpers.py
Description : Fonctions utilitaires réutilisables pour l'application GitLab Bridge.
              Centralise les helpers de normalisation de texte et de scoring,
              précédemment dupliqués dans projects.py, issues.py et groups.py.
Options éventuelles : Aucune.
Prérequis : Python 3.11+.
Auteur : Sylvain SCATTOLINI
Date de création / modification : 2026-04-09
Version : 1.0
"""

from __future__ import annotations

import re
import unicodedata
from difflib import SequenceMatcher


def normalize_text(value: str) -> str:
    """
    Normalise une chaîne pour la comparaison floue :
    suppression des accents, passage en minuscules, strip.
    """
    value = unicodedata.normalize("NFKD", value)
    value = "".join(char for char in value if not unicodedata.combining(char))
    return value.lower().strip()


def compute_similarity_score(a: str, b: str) -> int:
    """Retourne un score de similarité entre 0 et 100 entre deux chaînes normalisées."""
    return int(SequenceMatcher(None, normalize_text(a), normalize_text(b)).ratio() * 100)


def slugify(name: str) -> str:
    """
    Transforme un nom libre en slug GitLab valide (lettres, chiffres, tirets, points, underscores).
    Lève ValueError si le résultat est vide.
    """
    raw = normalize_text(name)
    raw = re.sub(r"\s+", "-", raw)
    raw = re.sub(r"[^a-zA-Z0-9._-]+", "-", raw)
    raw = re.sub(r"-{2,}", "-", raw).strip("-._")
    if not raw:
        raise ValueError(f"Impossible de générer un slug depuis : {name!r}")
    return raw