hykocx
74ce6192f1
- update README.md to simplify @zen/core description - rewrite DEV.md standards section with clearer principles and remove publication section - extract publication process to new PUBLICATION.md document - rewrite REDACTION.md with simplified structure and two-context approach - bump package version in package.json
2.5 KiB
Guide de développement
Ce document couvre les conventions de code, les règles de sécurité et la procédure de publication du package @zen/start.
Pour les conventions de rédaction : LANGUE.md et REDACTION.md.
Pour les conventions de commit : COMMITS.md.
Pour la procédure de publication du package : voir section Publication ci-dessous.
Contexte projet :
@zen/startest un CLI qui génère un projet Next.js avec@zen/coredéjà intégré. Partez du principe que le rôle de ce package est de scaffolder, il génère une structure de projet, il n'exécute pas de logique applicative.
Standards de code
Les promesses ne s'ignorent pas. Chaque Promise est awaitée ou .catch()ée. Une promesse silencieuse qui échoue est un bug invisible.
Les variables d'environnement et la documentation se mettent à jour avec le code. Toute variable ajoutée, renommée ou supprimée doit être reflétée dans .env.example. Toute décision architecturale ou convention nouvelle doit être documentée dans le fichier docs/ concerné.
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 variables réutilisées 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 du code. Un commentaire obsolète est pire qu'un commentaire absent — il induit en erreur. Quand on modifie une fonction, on met à jour son commentaire. Un commentaire qui contredit le code est un bug de documentation.
Sécurité
Données entrantes : toute donnée externe est considérée malveillante par défaut. On valide côté serveur uniquement.
Système de fichiers
On ne construit jamais un chemin par concaténation de chaînes brutes. On utilise path.join ou path.resolve :
// ✓
const dest = path.join(targetDir, 'package.json')
// ✗
const dest = targetDir + '/package.json'