010a7da0f4
Étape 4 du chantier de documentation. tools/ci-quality.sh porte les trois
vérifications qui se posent au même endroit — elles partagent la même sortie
(doc-generated/) et la même commande de réparation, les séparer ferait trois jobs
qui régénèrent trois fois la même chose :
1. l'index des règles est VRAI (code de retour de gen-rules.py) ;
2. la doc Doxygen est complète — 0 avertissement, DoD §5 ;
3. l'index est REPRODUCTIBLE : deux passes, un seul résultat.
PAS EN SERVICE, et l'extension le garantit : ci/gitea-workflow.yml.disabled ne
déclenche rien tant qu'il n'est pas déplacé dans .gitea/workflows/. La raison est
datée dans le fichier — forge muette, plus de trente commits en attente ici et
plus de soixante côté app ; un job activé à l'aveugle échouerait au moment précis
où tout le monde pousse, et le premier réflexe serait de le désactiver.
CHAQUE ÉCHEC DONNE LA COMMANDE À LANCER. Un job qui annonce « l'index est
périmé » sans dire quoi faire se contourne en le désactivant : c'est le chemin de
moindre effort, et il gagne toujours.
VÉRIFIÉ AVANT D'ÊTRE DÉCLARÉ PRÊT, et ça ne passait pas du premier coup.
— Les 26 avertissements Doxygen de ce matin sont CORRIGÉS, pas contournés par un
cliquet sur un compte de référence : c'était de la dette DoD-5 (retours et
paramètres non documentés dans relayrouter.h, energyarbitrator.h, loadconfig.h,
les trois clearFault(), ILoadAdapter::updateSoftConfig), plus deux que j'avais
introduits — un \rule{} dans un titre \par, et un \param energyLogs qui ne
correspond à aucun argument. Le seuil est donc ZÉRO, le seul qui ne rote pas.
— Et le script lui-même échouait sur un dépôt SAIN : `grep -c ... || echo 0`
affiche 0 PUIS sort en 1 quand il ne trouve rien, si bien que le « || » empile
un second zéro et que le test entier casse. Corrigé ici et dans gen-doc.sh, qui
portait le même piège. Une commande de mesure dont l'échec produit une lecture
fausse — le motif de la semaine, appliqué à l'outil.
CE QUI N'EST PAS VÉRIFIÉ, et pourquoi : « régénérer et refuser si ça diffère de
ce qui est commité » n'a rien à comparer, doc-generated/ étant dans .gitignore.
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é. Ce qui reste à
garantir est que l'index soit vrai (contrôle 1) et déterministe (contrôle 3).
État au 2026-08-29 : ./tools/ci-quality.sh → RC=0, 113 règles, 0 avertissement.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015F7G5VeaPVSMeVNjiGj36p
64 lines
3.3 KiB
Plaintext
64 lines
3.3 KiB
Plaintext
# ─────────────────────────────────────────────────────────────────────────────
|
|
# É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
|