Aller au contenu

ADR-051 : Insertion d'une méthode dans le contrôleur des pages publiques

Statut

Proposé, Forge 1.0.0-beta.17 (ticket ARCH-USER-CONTROLLER-REWRITE-ADR-001).

ADR distinct annoncé par l'ADR-030, qui a explicitement laissé hors de son périmètre la réécriture in-place d'un contrôleur utilisateur (« question distincte, à trancher séparément, principe 4 »).
Tant que cet ADR n'est pas accepté par le mainteneur, le comportement décrit reste celui livré, sans modification de la charte.

Date

2026-06-26

Contexte

forge make:public-page <Nom> génère une page publique : un template, une route (via le mécanisme d'injection cadré par l'ADR-030) et une méthode de contrôleur.
Cette dernière est posée par _ensure_controller_method (cli/public/public_page.py), qui écrit dans mvc/controllers/public_pages_controller.py, un fichier sous contrôle de l'utilisateur.

Trois cas se présentent :

  1. Fichier absent : Forge crée public_pages_controller.py avec la classe PublicPagesController et la méthode.
    C'est une écriture write-if-new, conforme au principe 9 (création d'un fichier nouveau).
  2. Méthode déjà présente : un test (def <méthode>() détecte la méthode ; Forge ne touche à rien.
    Comportement idempotent.
  3. Fichier présent sans la méthode : Forge insère la méthode dans la classe PublicPagesController existante.
    L'insertion repère la fin de la classe par analyse AST (ast.parse, ClassDef.end_lineno), insère le bloc de méthode, puis réécrit le fichier.

Le cas 3 est une modification in-place d'un fichier sous contrôle utilisateur, ce que le principe 4 (préserver le code utilisateur) et le principe 9 (pas d'écriture invisible) encadrent strictement.
C'est le point que l'ADR-030 a renvoyé à un ADR dédié.

Garde-fous déjà présents dans le code livré :

  • Explicite : l'écriture résulte d'une commande tapée par l'utilisateur (make:public-page), jamais d'un autre flux.
  • Idempotent : la présence de la méthode est détectée avant insertion (cas 2), ré-exécuter ne duplique pas.
  • Fail-safe : si le fichier ne parse pas (SyntaxError) ou si la classe PublicPagesController est absente, Forge n'écrit pas et renvoie un avertissement invitant à compléter le contrôleur manuellement.
  • Ciblé : l'insertion ne vise qu'un fichier et une classe de nom conventionnel Forge (public_pages_controller.py / PublicPagesController), jamais un contrôleur métier arbitraire.
  • Annoncé : make_public_page renvoie un résultat (controller_changed, avertissement éventuel) affiché à l'utilisateur.

Limite assumée : si l'utilisateur a écrit lui-même une classe PublicPagesController dans ce fichier conventionnel, Forge y insérera quand même la méthode.
Le nom est conventionnel et le fail-safe couvre les cas ambigus, mais l'écriture reste in-place.

Décision (proposée)

Acter le comportement du cas 3 comme conforme, en étendant au seul contrôleur des pages publiques les quatre conditions de l'ADR-030 (explicite, idempotent, délimité/visible, annoncé), renforcées par deux garanties propres au code utilisateur :

  1. Fail-safe : aucune écriture si le fichier ne parse pas ou si la classe cible est absente ; un avertissement oriente vers une complétion manuelle.
  2. Ciblé sur un nom conventionnel Forge : seul mvc/controllers/public_pages_controller.py / PublicPagesController est modifié, jamais un contrôleur métier arbitraire.

La charte (principe 4) sera précisée, après validation du mainteneur, pour distinguer la réécriture in-place silencieuse et arbitraire (interdite) de l'insertion explicite, idempotente, fail-safe et ciblée sur un fichier conventionnel généré par Forge (autorisée pour make:public-page).

Conséquences

  • make:public-page conserve sa valeur (câbler une page publique d'un geste) sans dégrader l'UX vers un mode « affichage » pur.
  • Le périmètre reste étroit : aucune autre commande n'est autorisée à modifier in-place un contrôleur ; les contrôleurs métier restent intouchables.
  • Un test de garde-fou pourra verrouiller les invariants (fail-safe sur fichier non parsable, idempotence, ciblage sur PublicPagesController).

Alternatives écartées

  • Re-scoper make:public-page en mode affichage (comme make:crud) : respecterait le principe 4 à la lettre mais imposerait à l'utilisateur de coller la méthode lui-même, dégradant une commande dont la valeur est le câblage d'un geste.
    Corriger ce symptôme plutôt que préciser la portée du principe 4 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 un principe non négociable, comme c'était le cas avant l'ADR-030.

Référence

  • ADR-030 : injection de routes par commande explicite, qui a renvoyé ce point à un ADR distinct.
  • cli/public/public_page.py (_ensure_controller_method).
  • Charte : CHARTE_DOC.md (principe 4, préserver le code utilisateur ; principe 9, pas d'écriture invisible ; règle d'évolution A).