Invariants
Ce sont les règles que le code refuse d'enfreindre. Aucune n'est une préférence de style. Chacune existe parce qu'un type de bug précis s'est produit, ou parce que la contourner casserait quelque chose de peu évident.
Elles étaient citées par numéro dans les commentaires du code — invariant 1/2/3/5/8 — sans être rassemblées nulle part. L'ADR 001 les a
mises par écrit ; cette page les explique.
Il y a cinq séries :
- I1 à I9, les invariants d'origine, reconstitués à partir du code, et la confidentialité des notes d'un écran.
- M1 à M8, apportés par Muse.
- Q1 à Q5, apportés par la passe de qualité.
- U1 à U5, apportés par Motion Ultra.
- D1 à D5, apportés par le tableau de bord d’administration.
Plus deux règles sans numéro qui comptent tout autant : la protection contre le SSRF, et la posture « pas de base de données, pas de dépendance native ».
Série I — le cœur#
I1. Jamais d'expression régulière sur du code source#
La règle. Ne jamais analyser du code généré ou copié avec une expression régulière pour découvrir des noms ou deviner ce qu'il contient. Il faut un vrai parcours de portée avec Babel.
Ce que ça protège. Une expression régulière ne sait pas ce qu'est une chaîne
de caractères. motion. apparaît à l'intérieur d'un littéral, à l'intérieur d'un
commentaire, et au milieu du mot promotion. Supprimer un import par motif de
ligne casse dès que la liste des éléments importés s'étale sur plusieurs lignes.
Comment c'est fait. stripForbiddenMotion(), dans src/lib/stripMotion.ts,
exécute un plugin Babel : ImportDeclaration pour les imports,
JSXMemberExpression pour
export/rewrite.ts transforme d'abord le JSX en React.createElement, ce qui
fait de chaque référence de composant un identifiant ordinaire, puis interroge la
portée.
Babel compile déjà ce code. Lui demander ce que le code est coûte une analyse et ne peut pas être trompé.
L'exception explicite. Analyser de la prose Markdown est autorisé.
export/theme.ts et extractDesignColors() lisent un DESIGN.md, pas du code,
et le disent en commentaire.
Le cas limite. tryDirectTextReplace() remplace un texte par correspondance
de chaîne, mais uniquement s'il apparaît exactement une fois, et uniquement
pour du texte que l'utilisateur regarde littéralement dans l'aperçu. Ce n'est pas
de la découverte de noms.
I2. L'iframe d'aperçu n'a pas d'origine propre#
La règle. L'aperçu est isolé avec allow-scripts et jamais
allow-same-origin. Ne jamais ajouter d'attribut crossorigin.
Ce que ça protège. Sans allow-same-origin, le document n'a pas d'origine :
pas de localStorage, donc pas de clé d'API ; pas de cookies ; pas d'accès au
DOM du parent. Or l'aperçu exécute en permanence du code écrit par un modèle.
Pourquoi pas de crossorigin. Comme le document n'a pas d'origine, cet
attribut transformerait chaque