Les gardes maison
Quatre scripts courts que lance pnpm check, chacun pour une erreur que ni TypeScript ni ESLint ne peuvent voir : un fichier de Next posé où Next ne le lit pas, un tutoriel qui vise un élément disparu, une carte des procédures périmée, une documentation qui cite ce qui n’existe plus. Comment chacun travaille, et comment en écrire un cinquième.
Précédemment. Le typecheck vérifie la cohérence des types, le lint les règles de React et du langage. Tous deux appliquent des règles générales, écrites pour n’importe quel projet.
Certaines erreurs n’appartiennent qu’à ce projet. Elles ont un point commun : rien ne les signale. Le code compile, le lint ne dit rien, la page s’affiche — et pourtant quelque chose ne fonctionne plus, ou la documentation ment. Pour chacune, le projet a écrit une garde : un script de quelques dizaines de lignes, lancé au début de pnpm check, qui cherche cette erreur-là et l’explique en français quand il la trouve.
Garde | Erreur silencieuse qu’elle cherche |
|---|---|
check-next-conventions.mjs | Un fichier de convention de Next (proxy, instrumentation) posé là où Next ne le lit pas : il est ignoré sans avertissement. |
check-tour-targets.mjs | Une étape de tutoriel interactif qui vise un élément renommé ou supprimé, un tuto absent du registre, un bouton de fiche ou un parcours qui désigne un tuto inconnu, un tuto sans fiche : le tutoriel se bloque, ou n’apparaît pas. |
build-procedure-map.mjs | Une carte des procédures qui ne correspond plus au backend : les parcours de la doc décrivent un code disparu. |
check-doc-entities.mjs | Une doc qui cite une entité, une propriété, une procédure ou une section qui n’existe plus. |
Showing entries1to4entries
Les fichiers que Next lit en silence 🧭#
Next reconnaît quelques fichiers à leur nom : proxy.ts (le filtre qui s’exécute avant chaque requête, ancien middleware.ts), instrumentation.ts (exécuté au démarrage du serveur). Il ne les cherche qu’à un endroit : le dossier qui contient app/. Ce projet range son application dans apps/web/src/app ; un proxy.ts posé dans apps/web/ serait ignoré, sans un mot. Le filtre d’authentification du tableau de bord ne s’exécuterait plus, et rien ne le dirait.
check-next-conventions.mjs
Clique une étape pour mettre en évidence la zone correspondante dans le fichier complet.
// ⚠ Fichier introuvable : scripts/check-next-conventions.mjs// Il a été déplacé ou supprimé depuis la rédaction de ce chapitre.C’est la garde la plus courte, et la plus typique : une erreur, cherchée par une règle simple, expliquée par une phrase qui dit quoi faire.
Les cibles des tutoriels#
Les tutoriels interactifs guident l’utilisateur pas à pas en mettant en valeur un élément de l’écran. Chaque étape désigne son élément par un nom (target: "posts.form.title"), et l’élément porte ce nom dans un attribut : data-tour="posts.form.title". C’est un contrat entre deux fichiers que rien ne relie pour TypeScript : renommer l’attribut casse le tutoriel, et le compilateur n’en sait rien.
check-tour-targets.mjs
Clique une étape pour mettre en évidence la zone correspondante dans le fichier complet.
// ⚠ Fichier introuvable : scripts/check-tour-targets.mjs// Il a été déplacé ou supprimé depuis la rédaction de ce chapitre.Avant de supprimer un data-tour, chercher son nom dans apps/web/src/features/tours/definitions/. La garde le ferait de toute façon, mais au moment du commit ; la recherche le fait au moment de la décision.
La carte des procédures, toujours à jour#
Les parcours de cette documentation montrent ce que fait chaque procédure : les entités qu’elle lit, crée, modifie ou supprime, les e-mails qu’elle envoie. Ces effets ne sont pas écrits à la main. build-procedure-map.mjs les relève dans le code du backend et les écrit dans un fichier JSON que la documentation lit.
Pour suivre un appel comme adapter.move(…) jusqu’à la fonction qui s’exécute vraiment, il faut savoir ce qu’est adapter. La garde charge donc le backend comme le fait l’éditeur, avec le vérificateur de types de TypeScript :
Le même script a deux usages. Avec --write, il régénère le fichier. Sans option, il le compare au fichier existant, et c’est ce mode que lance pnpm check :
Écrire, ou vérifier
Clique une étape pour mettre en évidence la zone correspondante dans le fichier complet.
// ⚠ Fichier introuvable : scripts/build-procedure-map.mjs// Il a été déplacé ou supprimé depuis la rédaction de ce chapitre.Ce motif — un fichier généré, versionné, et une vérification qu’il est à jour — vaut pour tout fichier produit à partir du code. Le fichier généré se relit dans une revue (on voit dans le diff qu’une procédure supprime désormais des messages), et la vérification garantit qu’on ne commite pas un backend modifié avec une carte d’hier.
Supprimer une fonction exportée du backend la retire aussi de la carte. La revue de cette partie en donne un exemple : la suppression de parsePathToDestination (chapitre 1) a fait échouer cette garde jusqu’à la régénération de la carte. C’est le comportement voulu : le diff de la carte montre ce que la suppression a retiré.
La documentation qui cite le code#
Chaque chapitre peut déclarer dans son en-tête les entités de la base qu’il concerne, et des parcours dont chaque étape appelle une procédure et renvoie à une section du chapitre. La documentation affiche ces déclarations sous forme de carte. Une entité renommée, une procédure supprimée, une section retitrée rendraient la carte fausse — sans erreur visible : la carte s’afficherait, avec un trou.
check-doc-entities.mjs
Clique une étape pour mettre en évidence la zone correspondante dans le fichier complet.
// ⚠ Fichier introuvable : scripts/check-doc-entities.mjs// Il a été déplacé ou supprimé depuis la rédaction de ce chapitre.Écrire une garde#
Les quatre gardes suivent le même modèle. Il sert de recette quand une nouvelle erreur silencieuse apparaît — et la réponse à une erreur silencieuse rencontrée une fois, c’est une garde de plus.
Règle | Pourquoi |
|---|---|
Une garde, une erreur | Un script qui vérifie une chose se lit en une minute ; on sait quand il se trompe. |
Lire le code comme du texte quand c’est possible | Une expression régulière ou une lecture ligne à ligne suffit souvent (data-tour, model X {). Le vérificateur de types est réservé à ce qui l’exige (suivre un appel). |
Un message qui dit quoi faire | Le fichier, ce qui manque, et la correction : « déplace-le », « lance pnpm docs:procedures ». |
Échouer par le code de sortie | process.exit(1) : pnpm check s’arrête, et le commit n’a pas lieu. |
Un bilan en cas de succès | Ce qui a été vérifié, et combien : une garde muette pourrait ne pas avoir tourné. |
Rapide | Quelques secondes au plus : elle passe avant le typecheck, à chaque commit. |
Showing entries1to6entries
Toutes ces gardes sont statiques : elles lisent des fichiers. Une erreur qui ne se voit qu’à l’exécution — une page qui répond mal, une règle de droits mal appliquée — demande d’exécuter le code, ce que font les tests.
Récapitulatif#
Question | Réponse du projet |
|---|---|
Pourquoi des gardes maison ? | Pour les erreurs propres au projet que ni TypeScript ni ESLint ne voient, et que rien d’autre ne signalerait. |
Que vérifie check-next-conventions ? | Que proxy et instrumentation sont dans apps/web/src, où Next les lit, et que middleware et proxy ne coexistent pas. |
Que vérifie check-tour-targets ? | Que chaque cible de tutoriel a son data-tour dans le code, que chaque tuto est au registre, que chaque bouton de fiche désigne un tuto existant, et que deux tutoriels n’ont pas le même identifiant. |
Comment la carte des procédures reste-t-elle juste ? | Elle est générée depuis le backend (--write) et versionnée ; pnpm check la régénère en mémoire et refuse un écart. |
Que vérifie check-doc-entities ? | Les entités, propriétés, procédures et sections citées par l’en-tête de chaque chapitre. |
Comment écrire une garde ? | Une erreur, un script court, un message qui dit quoi faire, exit 1, un bilan en cas de succès. |
Showing entries1to6entries
À suivre#
Les gardes, le typecheck et le lint lisent le code sans l’exécuter. Ce qui ne se voit qu’à l’exécution — une règle de droits, un brouillon montré à qui ne devrait pas le voir, un e-mail qui n’arrive pas — demande d’exécuter le site, dans un vrai navigateur.
Chapitre suivant : tester de bout en bout. Playwright contre l’application construite pour la production, une base et un stockage réservés aux tests, et six parcours sur les règles du club.