Aller au contenu

ADR-030 : Injection de routes par commande explicite et règle 4.3

Statut

Acceptée, Forge 1.0.0-beta.17 (ticket GOV-ADR-STATUS-RESOLVE-001).
Proposé en 1.0.0-beta.15 (ticket ADR-EXPLICIT-ROUTE-INJECTION-001), révisé en 1.0.0-beta.17 (ticket ADR-030-REVISION-001) pour retirer la référence à starter:build, commande supprimée par l'ADR-035.

La décision est appliquée dans le code : les make:public-* injectent les routes selon les quatre conditions, avec détection robuste du marqueur router (FIX-PUBLIC-ROUTES-MARKER-001).
La précision du texte de la règle 4.3 de CHARTE_DOC.md reste un geste mainteneur distinct, non appliqué par cet ADR.

Précise la portée de la règle de génération 4.3 de la charte v2 (« le fichier principal de routes applicatives mvc/routes.py reste sous le contrôle explicite du développeur ; pas de marqueurs commentaires auto-injectés, pas de réécriture automatique »).
Aucune modification de CHARTE_DOC.md n'est appliquée tant que le mainteneur n'a pas validé cet ADR.

Date

2026-06-08 (révisé le 2026-06-19).

Contexte

La règle 4.3 de la charte v2 interdit la réécriture automatique de mvc/routes.py.
Or les commandes make:public-* l'écrivent aujourd'hui :

  • forge make:public-page, make:public-list, make:public-form, make:public-show et make:public-contact insèrent un import et un bloc de route dans le mvc/routes.py existant (cli/public/public_page.py, public_list.py, public_form.py, etc.).

Note historique : un second injecteur, forge starter:build, encadrait son bloc par des marqueurs # forge-starter:<nom>:start / :end et ajustait la route racine.
Cette commande a été supprimée par l'ADR-035 (bêta.16, retrait de la génération de starters).
Le présent ADR ne couvre donc plus que les make:public-*.

Cette injection est un choix délibéré, jamais réconcilié avec la lettre de la règle 4.3.
Un auditeur strict peut donc considérer le comportement livré comme non conforme à une règle marquée « non négociable ».

Dans le même temps, le générateur make:crud n'injecte pas : il affiche le bloc de routes sur la sortie standard, à coller manuellement.
Il existe donc deux comportements selon le générateur.

Le point à trancher : la règle 4.3 interdit-elle toute écriture dans mvc/routes.py, ou seulement l'écriture silencieuse et automatique que le développeur n'a pas demandée ?

Décision

La règle 4.3 vise l'écriture silencieuse et automatique : Forge ne doit jamais réécrire mvc/routes.py de sa propre initiative, en arrière-plan, sans geste de l'utilisateur.
Elle n'interdit pas une commande de scaffolding que le développeur invoque explicitement.

Une commande Forge est autorisée à injecter des routes dans mvc/routes.py si, et seulement si, les quatre conditions suivantes sont réunies :

  1. Explicite : l'écriture résulte d'une commande que l'utilisateur tape lui-même (make:public-*).
    Aucune écriture déclenchée par un autre flux (démarrage, autre générateur, hook) n'est permise.
  2. Idempotente : ré-exécuter la commande ne duplique pas le bloc ; la présence du bloc (ou de la route) est détectée avant insertion.
  3. Délimitée et visible : le bloc injecté est clairement identifiable, de sorte que le développeur voie et puisse retirer ce qui a été ajouté.
  4. Annoncée : la commande signale sur la sortie standard ce qu'elle a écrit (fichier touché, route ajoutée).

Toute détection de point d'injection se fait de manière robuste (analyse AST ou ancrage fiable), jamais par simple sous-chaîne susceptible d'être trompée par un commentaire ou une chaîne (cf. correctif FIX-PUBLIC-ROUTES-MARKER-001).

Le mode affichage de make:crud reste une variante conservatrice acceptable et n'a pas à être aligné sur l'injection : pour un générateur d'entité unique, laisser le développeur coller lui-même la route est un choix légitime.
Les deux modes coexistent, chacun adapté à son contexte (scaffolding d'une page publique vs route d'une entité).

Conséquences

  • La charte (règle 4.3) sera précisée, après validation du mainteneur, pour distinguer « réécriture silencieuse/automatique » (interdite) de « injection par commande explicite répondant aux quatre conditions » (autorisée).
  • Les make:public-* sont conformes dès lors qu'ils respectent les quatre conditions ; le correctif de détection robuste du marqueur router (FIX-PUBLIC-ROUTES-MARKER-001) renforce la condition 2.
  • Les contrôleurs applicatifs (mvc/controllers/*.py) ne sont pas couverts par cette autorisation : la réécriture in-place d'un contrôleur utilisateur reste une question distincte, à trancher séparément (principe 4, préservation du code utilisateur).
  • Aucune écriture dans mvc/routes.py hors commande explicite ne devient permise ; le périmètre reste étroit.

Alternatives écartées

  • Tout basculer en mode affichage (comme make:crud) : respecterait 4.3 à la lettre mais dégraderait l'UX des make:public-*, dont la valeur est de câbler la page d'un geste.
    Corriger ce symptôme plutôt que la portée trop large de 4.3 contredit la règle d'évolution A (retirer la cause, pas le symptôme).
  • Laisser la contradiction implicite : expose à un reproche d'audit récurrent sur une règle « non négociable ».

Référence

  • ADR-023 starter:build canonique (commande retirée depuis par l'ADR-035) : ADR-023.
  • ADR-035 starters réalisés à la main (retrait de la génération) : ADR-035.
  • Correctif de détection robuste du router : FIX-PUBLIC-ROUTES-MARKER-001.
  • Charte : CHARTE_DOC.md (règle 4.3 ; règle d'évolution A).