# ─────────────────────────────────────────────────────────────────────────────
#  ÉCRIT, PAS EN SERVICE — et l'extension `.disabled` est ce qui le garantit.
#
#  POUR L'ACTIVER, quand la forge répondra et que le retard de commits sera résorbé :
#
#      mkdir -p .gitea/workflows
#      git mv ci/gitea-workflow.yml.disabled .gitea/workflows/qualite-doc.yml
#
#  Le déposer ailleurs que dans `.gitea/workflows/` ne déclenche rien : c'est
#  volontaire. Un fichier renommé est un geste ; un fichier au bon endroit est un
#  service.
#
#  POURQUOI PAS MAINTENANT (2026-08-29). La forge ne répond pas et plus de trente
#  commits attendent en local dans ce dépôt, plus de soixante côté app. Un job
#  activé à l'aveugle échouerait à son premier passage — au moment précis où tout
#  le monde pousse — et le premier réflexe serait de le désactiver. Un garde-fou
#  désactivé une fois ne se réactive jamais.
#
#  AVANT D'ACTIVER, lancer le contrôle À LA MAIN sur la branche visée :
#
#      ./tools/ci-quality.sh
#
#  Il passait sur l'état du dépôt au 2026-08-29 — index RC=0 (113 règles), doxygen
#  0 avertissement. S'il échoue, la cause est dans le dépôt, pas dans le job : le
#  corriger AVANT l'activation, jamais après. Un job qu'on n'a jamais vu passer
#  n'est pas un job, c'est une intention.
#
#  CE QU'IL VÉRIFIE — trois choses, un seul endroit, parce qu'elles partagent la
#  même sortie et la même commande de réparation :
#    1. l'index des règles est VRAI (orphelins, domiciles ambigus, numéros retirés
#       réattribués) ;
#    2. la documentation Doxygen est complète (0 avertissement, DoD §5) ;
#    3. l'index est REPRODUCTIBLE (deux passes, un seul résultat).
#
#  Ce qu'il ne vérifie PAS : « régénérer et refuser si ça diffère de ce qui est
#  commité ». `doc-generated/` est dans .gitignore ; il n'y a rien à comparer, et
#  le risque qu'un tel diff attraperait — un artefact commité qui dérive de sa
#  source — a été SUPPRIMÉ en ne le commitant pas, pas déplacé.
# ─────────────────────────────────────────────────────────────────────────────
name: qualité documentaire

on:
  push:
    branches: [ feature/beta-rulebased, main ]
  pull_request:

jobs:
  qualite-doc:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      # doxygen ET graphviz : dépendances de la CIBLE DOC uniquement, jamais du
      # build du paquet. Sans elles le contrôle 2 ne s'exécute pas — et il le DIT
      # au lieu de passer en silence, ce qui serait un faux vert.
      - name: dépendances de la cible doc
        run: sudo apt-get update && sudo apt-get install -y doxygen graphviz python3

      # Une commande unique, celle qu'un humain lance. Si le job et la machine de
      # développement divergeaient, le job cesserait d'être reproductible chez soi
      # — et un contrôle qu'on ne peut pas rejouer localement se contourne.
      - name: contrôle de qualité documentaire
        run: ./tools/ci-quality.sh