Vérificateur de liens — doc HTML Kohinos

La doc statique dochtml/ regroupe près d'une centaine de pages reliées entre elles par des liens relatifs. Sans contrôle automatisé, un renommage de page ou la suppression d'une ancre passe inaperçu. Ce script Python local — sans dépendance externe, sans appel réseau par défaut — détecte les liens cassés et les ancres manquantes avant qu'un lecteur ne tombe sur un 404.

Pourquoi un script maison

• Souveraineté — pas de service SaaS (DeadLinkChecker.com, W3C checklink hébergé : hors-jeu).
• Offline-friendly — exécutable sur un Raspberry Pi déconnecté, sur la machine de dev sans internet, dans un pipeline Woodpecker sans accès sortant.
• Zéro dépendance — uniquement la stdlib Python 3.11 ; aucun pip install à maintenir.
• Reproductible — sortie identique sur tout poste pour le même état du dossier dochtml/.

Ce que le script vérifie

Type de lien	Vérification	Réseau ?
Interne relatif (./page.html, ../dev/api.html)	Le fichier cible existe sur le disque	Non
Ancre intra-page (#section)	L'id ou name existe dans la page courante	Non
Ancre cross-page (./page.html#section)	Fichier et ancre existent	Non
Externe (https://...)	Ignoré sauf si --check-external (HEAD HTTP, timeout 5 s)	Oui — opt-in
mailto:, tel:, javascript:, data:	Ignorés	Non

Usage local

python3 scripts/check-doc-links.py
python3 scripts/check-doc-links.py --json --check-external

• Sortie colorée sur terminal (rouge = cassé, vert = OK).
• Code retour 0 si tout OK, 1 si liens cassés détectés — utilisable directement en pré-commit ou en CI.
• --json exporte un rapport horodaté dans var/log/doc-links-<timestamp>.json (utile en pipeline pour conserver un artefact).

Intégration Woodpecker CI

Le moteur CI est Woodpecker (cf. page CI/CD + ADR 0028). Une pipeline financière ne doit jamais être ralentie ou bloquée par un lien cassé sur une page de doc : la vérification de liens est donc un step non bloquant (failure: ignore), idéalement isolé dans le pipeline nightly.yml plutôt que dans pr.yml/main.yml.

# Step à ajouter à .woodpecker/nightly.yml (non bloquant) :
  - name: docs-link-check
    image: php:8.4-cli-alpine
    commands:
      - php scripts/check-doc-links.php
    failure: ignore   # un lien mort ne doit jamais bloquer un correctif financier

Caractéristiques recommandées du step :

• placé dans nightly.yml (diagnostic) — hors du chemin critique PR/merge,
• failure: ignore — un correctif urgent ne doit jamais être bloqué par un lien mort,
• peut publier le rapport JSON via un volume /cache si une conservation est souhaitée.

🛈 À ce jour ce step n'est pas encore câblé dans .woodpecker/*.yml : la vérification se lance manuellement en local. L'ajouter à nightly.yml reste une évolution à planifier.

Sortie type

Vérification des liens documentation Kohinos
  Répertoire     : /home/julien/kohinos/dochtml
  Pages scannées : 88
  Liens analysés : 1950
  OK             : 1583
  Externes ignorés : 357 (activer avec --check-external)

[KO] 9 lien(s) cassé(s) :
  - dochtml/user/glossaire.html  →  #flux
      anchor : ancre #flux absente de la page

Limites connues

• Parsing HTML par regex : suffisant pour la doc statique générée, mais ne gère pas le HTML produit par du JS côté client (sans objet ici).
• Les ancres générées dynamiquement (TOC JS) ne sont pas détectées tant qu'elles ne sont pas écrites en dur dans le HTML servi.
• Les liens en srcset, poster, data-src ne sont pas vérifiés — uniquement href. Voir page observabilité si un audit images devient nécessaire.

Liens utiles