Conventions de code

Ces règles s'appliquent à @lrvo/core et aux packages @lrvo/module-*.

Contexte projet : les utilisateurs finaux créent leur projet via npx @lrvo/start, qui génère une structure Next.js avec la plateforme déjà intégrée. Lors d'une assistance ou d'une revue, partir du principe que le projet cible est structuré ainsi.

Standards

On corrige la cause racine, jamais les symptômes. Si le même type d'erreur réapparaît dans un deuxième fichier après avoir corrigé le premier, c'est le signe que le vrai correctif est ailleurs. Remonter la chaîne d'imports ou d'appels jusqu'à comprendre pourquoi ce code est atteint dans ce contexte, puis corriger à cet endroit. Patcher les fichiers un par un masque le problème et garantit qu'un troisième cas surgira.

Les promesses ne s'ignorent pas. Chaque Promise est attendue ou capturée. Une promesse silencieuse qui échoue est un bug invisible.

Une fonction, une responsabilité. Si elle fait deux choses, c'est deux fonctions. Si elle ne tient pas sur un écran, la découper.

Le flux de contrôle se lit de haut en bas. Pas de récursion non bornée, pas de callbacks imbriqués à plus de deux niveaux. Quelqu'un qui lit le code pour la première fois doit pouvoir suivre l'exécution sans se perdre.

Les données entrantes sont suspectes. On valide en entrée de fonction. On ne suppose pas que l'appelant a fait le travail.

La portée des variables est minimale. On déclare au plus près de l'usage. Pas de variable réutilisée pour deux rôles différents.

ESLint passe sans avertissement. Un warning ignoré aujourd'hui est un bug non détecté demain.

Les commentaires reflètent toujours le comportement réel. Un commentaire obsolète est pire qu'un commentaire absent : il induit en erreur. Quand on modifie une fonction, on met à jour son commentaire.

Arborescence

Une feature (src/features/<nom>/ ou src/core/<nom>/) suit la règle plat plus un barrel : un index.js qui ré-exporte, et des fichiers plats côte à côte pour l'implémentation.

Pas de sous-dossier lib/, middleware/ ou actions/ quand il ne contient qu'un ou deux fichiers : remonter directement au niveau du dossier de la feature.

Les sous-dossiers sont autorisés uniquement quand ils contiennent plusieurs fichiers du même rôle : components/, pages/, templates/, widgets/.

Suffixes de runtime

Ces suffixes ne sont pas cosmétiques : le build les utilise comme source de vérité. Tout fichier qui importe pg, fs, net ou node:* doit porter .server.js. Le détail et les pièges sont dans Frontières serveur/client.

Langue

Le code est en anglais, le contenu visible et la documentation en français. Voir Langue et Rédaction.

Documentation

Toute la documentation vit dans docs/. Aucun fichier .md ne réside dans src/.

Une modification de code n'est pas terminée tant que la page concernée n'est pas à jour :

• docs/03-reference/ pour le comportement d'un module, d'une fonction, d'une commande.
• docs/04-architecture/ pour une décision structurelle ou une convention transverse.
• docs/02-guides/ pour un cas d'usage nouveau ou modifié.
• docs/06-modules/ pour le comportement d'un package @lrvo/module-*.

Les variables d'environnement se mettent à jour avec le code. Toute variable ajoutée, renommée ou supprimée doit être reflétée dans le catalogue src/core/doctor/env.js et dans Variables d'environnement. npm run build échoue tant que le catalogue et le code divergent, dans un sens comme dans l'autre.

.env.example ne suit pas la même règle : c'est le modèle de démarrage copié par @lrvo/start, qui ne reçoit que les variables qu'un nouveau projet doit remplir. Toute clé qu'il porte doit exister au catalogue, l'inverse est faux et voulu.

Ajouter un point d'entrée public = éditer package.json#exports et l'ajouter au tableau de Points d'entrée.

Sécurité

Les règles de sécurité sont dans Sécurité : validation des entrées, requêtes paramétrées, gestion des secrets, erreurs opaques, traitement des vulnérabilités transitives.

Commits

Format Conventional Commits, en anglais. Voir Commits.