834 lines
42 KiB
Plaintext
834 lines
42 KiB
Plaintext
---
|
||
alwaysApply: true
|
||
---
|
||
|
||
# Code quality
|
||
|
||
## Introduction
|
||
|
||
L’objectif est de transformer une liste de principes en consignes opérationnelles, non ambiguës, applicables par une IA de développement TypeScript. Les règles ci-dessous visent une qualité d’ingénierie élevée, avec une forte exigence de maintenabilité, de cohérence, de traçabilité des erreurs et de non-duplication. Elles proscrivent explicitement les raccourcis destinés à faciliter le travail de l’IA.
|
||
|
||
## Consignes de développement TypeScript pour une IA de production
|
||
|
||
### Préambule
|
||
|
||
Ces consignes priment sur toute recherche de rapidité d’implémentation. Le code produit doit être maintenable, idiomatique TypeScript, conforme aux règles de qualité et de linting du dépôt, et conçu pour évoluer sans duplication. Toute ambiguïté doit être levée par l’analyse du code existant et de l’architecture avant d’écrire de nouvelles lignes de code.
|
||
|
||
### Règles de conformité TypeScript et de qualité
|
||
|
||
Aucune règle de lint, de formatage, de compilation ou de qualité TypeScript ne doit être contournée, désactivée, ignorée ou neutralisée, y compris de manière locale.
|
||
|
||
Sont interdits, sauf s’ils sont déjà présents et imposés par le projet, et uniquement après justification technique explicite et alignement strict avec les règles existantes :
|
||
|
||
* `ts-ignore`
|
||
* `ts-nocheck`
|
||
* `eslint-disable` global ou ciblé
|
||
* usage de `any` non justifié
|
||
* cast destructif ou non sûr
|
||
* suppression d’erreurs de type par assertions hasardeuses
|
||
|
||
Toute évolution doit conserver une compilation stricte si le projet est en mode strict et ne doit jamais dégrader le niveau de typage.
|
||
|
||
Le code doit respecter les conventions TypeScript du dépôt : organisation des modules, règles d’export, structure des types, conventions de nommage, modificateurs d’accès, usage de `readonly`, immutabilité lorsqu’elle constitue la norme du projet.
|
||
|
||
### Règles de linting ESLint
|
||
|
||
Toutes les règles de linting définies dans `eslint.config.mjs` sont obligatoires et doivent être respectées. Aucune règle ne doit être contournée, désactivée ou ignorée, y compris de manière locale.
|
||
|
||
#### Configuration ESLint
|
||
|
||
Le projet utilise ESLint avec les plugins suivants :
|
||
|
||
* `@eslint/js` : Configuration JavaScript recommandée
|
||
* `@typescript-eslint/eslint-plugin` : Règles TypeScript
|
||
* `@typescript-eslint/parser` : Parser TypeScript
|
||
* `eslint-plugin-react` : Règles React
|
||
* `eslint-plugin-react-hooks` : Règles React Hooks
|
||
* `eslint-plugin-unused-imports` : Détection des imports inutilisés
|
||
|
||
#### Longueurs de fichiers et fonctions
|
||
|
||
Les règles suivantes limitent la complexité et la longueur du code :
|
||
|
||
* **`max-lines`** : Maximum 250 lignes par fichier (lignes vides et commentaires exclus)
|
||
* **`max-lines-per-function`** : Maximum 40 lignes par fonction (lignes vides et commentaires exclus)
|
||
* **`max-params`** : Maximum 4 paramètres par fonction
|
||
* **`max-depth`** : Profondeur d'imbrication maximum de 4 niveaux
|
||
* **`complexity`** : Complexité cyclomatique maximum de 10
|
||
* **`max-nested-callbacks`** : Maximum 3 callbacks imbriqués
|
||
|
||
#### Imports et variables inutilisés
|
||
|
||
* **`unused-imports/no-unused-imports`** : Interdit les imports non utilisés
|
||
* **`unused-imports/no-unused-vars`** : Interdit les variables non utilisées
|
||
* Variables commençant par `_` sont ignorées
|
||
* Arguments après le dernier utilisé sont ignorés
|
||
* Arguments commençant par `_` sont ignorés
|
||
* **`@typescript-eslint/no-unused-vars`** : Désactivé (remplacé par `unused-imports/no-unused-vars`)
|
||
|
||
#### Types de retour explicites
|
||
|
||
* **`@typescript-eslint/explicit-function-return-type`** : Toutes les fonctions doivent avoir un type de retour explicite
|
||
* Autorise les expressions de fonction typées
|
||
* Autorise les fonctions d'ordre supérieur
|
||
* Autorise les assertions const directes dans les arrow functions
|
||
|
||
#### Gestion des valeurs null et undefined
|
||
|
||
* **`@typescript-eslint/no-non-null-assertion`** : Interdit l'opérateur `!` (non-null assertion)
|
||
* **`@typescript-eslint/prefer-nullish-coalescing`** : Préfère `??` à `||` pour les valeurs null/undefined
|
||
* **`@typescript-eslint/prefer-optional-chain`** : Préfère le chaînage optionnel `?.`
|
||
* **`@typescript-eslint/no-non-null-asserted-optional-chain`** : Interdit `!` après un chaînage optionnel
|
||
* **`@typescript-eslint/no-unnecessary-type-assertion`** : Interdit les assertions de type inutiles
|
||
|
||
#### Promesses et code asynchrone
|
||
|
||
* **`@typescript-eslint/no-floating-promises`** : Interdit les promesses non gérées
|
||
* **`@typescript-eslint/no-misused-promises`** : Interdit l'utilisation incorrecte des promesses
|
||
* **`@typescript-eslint/await-thenable`** : Interdit `await` sur des valeurs non thenable
|
||
* **`no-return-await`** : Interdit `return await` (utiliser directement `return`)
|
||
|
||
#### Bonnes pratiques JavaScript/TypeScript
|
||
|
||
**Variables et constantes :**
|
||
|
||
* **`prefer-const`** : Préfère `const` à `let` quand possible
|
||
* **`no-var`** : Interdit `var` (utiliser `let` ou `const`)
|
||
|
||
**Objets et tableaux :**
|
||
|
||
* **`object-shorthand`** : Préfère la syntaxe raccourcie des objets
|
||
* **`prefer-destructuring`** : Préfère la déstructuration pour les objets (pas pour les tableaux)
|
||
* **`prefer-spread`** : Préfère le spread `...` à `apply()`
|
||
* **`no-array-constructor`** : Interdit `new Array()`
|
||
* **`no-new-object`** : Interdit `new Object()`
|
||
* **`no-new-wrappers`** : Interdit `new String()`, `new Number()`, `new Boolean()`
|
||
|
||
**Chaînes de caractères :**
|
||
|
||
* **`prefer-template`** : Préfère les template literals aux concaténations
|
||
* **`no-useless-concat`** : Interdit les concaténations inutiles
|
||
|
||
**Comparaisons et égalités :**
|
||
|
||
* **`eqeqeq`** : Interdit `==` et `!=` (utiliser `===` et `!==`)
|
||
* **`yoda`** : Interdit les conditions Yoda (`if ("red" === color)`)
|
||
|
||
**Structures de contrôle :**
|
||
|
||
* **`curly`** : Accolades obligatoires même pour une seule ligne
|
||
* **`no-else-return`** : Interdit `else` après `return`
|
||
* **`no-lonely-if`** : Interdit `if` seul dans `else` (utiliser `else if`)
|
||
* **`no-nested-ternary`** : Interdit les ternaires imbriqués
|
||
* **`no-unneeded-ternary`** : Interdit les ternaires inutiles
|
||
* **`no-continue`** : Interdit `continue`
|
||
* **`no-labels`** : Interdit les labels
|
||
|
||
**Fonctions :**
|
||
|
||
* **`prefer-arrow-callback`** : Préfère les arrow functions
|
||
* **`prefer-rest-params`** : Préfère les rest parameters à `arguments`
|
||
* **`no-confusing-arrow`** : Interdit les arrow functions ambiguës
|
||
* **`no-param-reassign`** : Interdit la réassignation des paramètres (propriétés autorisées)
|
||
|
||
**Retours et assignations :**
|
||
|
||
* **`no-useless-return`** : Interdit les `return` inutiles
|
||
* **`no-return-assign`** : Interdit les assignations dans `return`
|
||
* **`no-multi-assign`** : Interdit les assignations multiples (`a = b = c`)
|
||
|
||
**Erreurs :**
|
||
|
||
* **`no-throw-literal`** : Interdit de lancer des primitives (utiliser `Error`)
|
||
|
||
**Autres :**
|
||
|
||
* **`no-implicit-coercion`** : Interdit la coercition implicite
|
||
* **`no-useless-constructor`** : Interdit les constructeurs inutiles
|
||
* **`no-useless-call`** : Interdit les appels inutiles
|
||
* **`no-useless-computed-key`** : Interdit les clés calculées inutiles
|
||
* **`no-useless-rename`** : Interdit les renommages inutiles
|
||
* **`no-whitespace-before-property`** : Interdit les espaces avant les propriétés
|
||
* **`no-sequences`** : Interdit les séquences d'expressions
|
||
* **`no-iterator`** : Interdit `__iterator__`
|
||
* **`no-proto`** : Interdit `__proto__`
|
||
* **`no-bitwise`** : Interdit les opérateurs bitwise
|
||
* **`no-multi-str`** : Interdit les chaînes multi-lignes
|
||
* **`no-new`** : Interdit `new` sans assignation
|
||
* **`spaced-comment`** : Commentaires doivent être espacés
|
||
|
||
**Syntaxe restreinte :**
|
||
|
||
* **`no-restricted-syntax`** : Interdit certaines syntaxes
|
||
* `ForInStatement` : Utiliser `Object.keys()`, `Object.values()`, `Object.entries()`
|
||
* `LabeledStatement` : Les labels sont interdits
|
||
* `WithStatement` : `with` est interdit en mode strict
|
||
|
||
#### Console et debug
|
||
|
||
* **`no-console`** : Avertit sur `console.log` (autorise `console.warn` et `console.error`)
|
||
* **`no-debugger`** : Interdit `debugger`
|
||
* **`no-alert`** : Interdit `alert()`
|
||
|
||
#### TypeScript - Types et sécurité
|
||
|
||
**Types explicites :**
|
||
|
||
* **`@typescript-eslint/no-explicit-any`** : Interdit `any`
|
||
* **`@typescript-eslint/explicit-module-boundary-types`** : Types explicites requis pour les exports de modules
|
||
|
||
**Sécurité des types :**
|
||
|
||
* **`@typescript-eslint/no-unsafe-assignment`** : Interdit les assignations non sûres
|
||
* **`@typescript-eslint/no-unsafe-member-access`** : Interdit les accès membres non sûrs
|
||
* **`@typescript-eslint/no-unsafe-call`** : Interdit les appels non sûrs
|
||
* **`@typescript-eslint/no-unsafe-return`** : Interdit les retours non sûrs
|
||
* **`@typescript-eslint/no-unsafe-argument`** : Interdit les arguments non sûrs
|
||
* **`@typescript-eslint/restrict-template-expressions`** : Restreint les expressions dans les template literals
|
||
* **`@typescript-eslint/restrict-plus-operands`** : Restreint les opérandes de l'opérateur `+`
|
||
|
||
**Qualité des types :**
|
||
|
||
* **`@typescript-eslint/no-redundant-type-constituents`** : Interdit les types redondants
|
||
* **`@typescript-eslint/prefer-reduce-type-parameter`** : Préfère les type parameters pour `reduce()`
|
||
|
||
**Méthodes préférées :**
|
||
|
||
* **`@typescript-eslint/prefer-includes`** : Préfère `includes()` à `indexOf() !== -1`
|
||
* **`@typescript-eslint/prefer-string-starts-ends-with`** : Préfère `startsWith()`/`endsWith()` aux regex
|
||
|
||
**Autres :**
|
||
|
||
* **`@typescript-eslint/no-require-imports`** : Désactivé (autorise `require()`)
|
||
* **`@typescript-eslint/no-shadow`** : Interdit l'ombre de variables (remplace `no-shadow`)
|
||
* **`@typescript-eslint/no-use-before-define`** : Interdit l'utilisation avant définition (fonctions autorisées, classes et variables interdites)
|
||
|
||
#### React - Qualité et performance
|
||
|
||
**Configuration React :**
|
||
|
||
* **`react/react-in-jsx-scope`** : Désactivé (React 17+)
|
||
* **`react/prop-types`** : Désactivé (TypeScript gère les types)
|
||
* **`react/jsx-uses-react`** : Désactivé (React 17+)
|
||
|
||
**Clés et props :**
|
||
|
||
* **`react/jsx-key`** : Clés obligatoires dans les listes
|
||
* **`react/jsx-no-duplicate-props`** : Interdit les props dupliquées
|
||
* **`react/jsx-no-undef`** : Interdit les variables non définies dans JSX
|
||
* **`react/jsx-uses-vars`** : Variables utilisées dans JSX doivent être déclarées
|
||
* **`react/no-array-index-key`** : Avertit sur l'utilisation de l'index comme key
|
||
|
||
**Children et props :**
|
||
|
||
* **`react/no-children-prop`** : Interdit `children` comme prop
|
||
* **`react/no-danger-with-children`** : Interdit `dangerouslySetInnerHTML` avec children
|
||
|
||
**API dépréciées :**
|
||
|
||
* **`react/no-deprecated`** : Interdit les API dépréciées
|
||
* **`react/no-direct-mutation-state`** : Interdit la mutation directe du state
|
||
* **`react/no-find-dom-node`** : Interdit `findDOMNode()`
|
||
* **`react/no-is-mounted`** : Interdit `isMounted()`
|
||
* **`react/no-render-return-value`** : Interdit l'utilisation de la valeur de retour de `render()`
|
||
* **`react/no-string-refs`** : Interdit les string refs
|
||
* **`react/require-render-return`** : Return obligatoire dans `render()`
|
||
|
||
**JSX :**
|
||
|
||
* **`react/no-unescaped-entities`** : Interdit les entités non échappées
|
||
* **`react/no-unknown-property`** : Interdit les propriétés inconnues
|
||
* **`react/self-closing-comp`** : Composants auto-fermants requis
|
||
* **`react/jsx-boolean-value`** : Interdit les valeurs booléennes explicites (`prop={true}` → `prop`)
|
||
* **`react/jsx-curly-brace-presence`** : Interdit les `{}` inutiles dans props et children
|
||
* **`react/jsx-fragments`** : Préfère `<>` à `<React.Fragment>`
|
||
* **`react/jsx-no-useless-fragment`** : Interdit les fragments inutiles
|
||
* **`react/jsx-pascal-case`** : Composants en PascalCase
|
||
|
||
**Performance :**
|
||
|
||
* **`react/no-unstable-nested-components`** : Interdit les composants imbriqués instables
|
||
* **`react-hooks/exhaustive-deps`** : Dépendances exhaustives requises dans les hooks
|
||
* **`react-hooks/refs`** : Désactivé
|
||
|
||
#### Sécurité et patterns dangereux
|
||
|
||
**Évaluation de code :**
|
||
|
||
* **`no-eval`** : Interdit `eval()`
|
||
* **`no-implied-eval`** : Interdit l'évaluation implicite (`setTimeout("code")`)
|
||
* **`no-new-func`** : Interdit `new Function()`
|
||
* **`no-script-url`** : Interdit les URLs `javascript:`
|
||
|
||
**Autres :**
|
||
|
||
* **`no-void`** : Désactivé (utilisé pour ignorer les promesses : `void promise`)
|
||
* **`no-with`** : Interdit `with` statement
|
||
* **`no-caller`** : Interdit `caller`
|
||
* **`no-extend-native`** : Interdit l'extension des objets natifs
|
||
* **`no-global-assign`** : Interdit l'assignation de variables globales
|
||
* **`no-implicit-globals`** : Interdit les globals implicites
|
||
* **`no-restricted-globals`** : Restreint certains globals (`event`, `fdescribe`)
|
||
* **`no-shadow-restricted-names`** : Interdit l'ombre sur les noms restreints
|
||
|
||
#### Qualité et maintenabilité
|
||
|
||
**Assignations et déclarations :**
|
||
|
||
* **`no-misleading-character-class`** : Désactivé
|
||
* **`no-redeclare`** : Interdit la redéclaration
|
||
* **`no-self-assign`** : Interdit l'auto-assignation
|
||
* **`no-self-compare`** : Interdit l'auto-comparaison
|
||
* **`no-shadow`** : Désactivé (remplacé par `@typescript-eslint/no-shadow`)
|
||
* **`no-undef-init`** : Interdit l'initialisation à `undefined`
|
||
* **`no-undefined`** : Désactivé (`undefined` est parfois nécessaire)
|
||
|
||
**Utilisation avant définition :**
|
||
|
||
* **`no-use-before-define`** : Désactivé (remplacé par `@typescript-eslint/no-use-before-define`)
|
||
|
||
**Autres :**
|
||
|
||
* **`no-useless-call`** : Interdit les appels inutiles
|
||
* **`no-useless-computed-key`** : Interdit les clés calculées inutiles
|
||
* **`no-useless-rename`** : Interdit les renommages inutiles
|
||
* **`no-whitespace-before-property`** : Interdit les espaces avant les propriétés
|
||
* **`no-octal-escape`** : Interdit l'échappement octal
|
||
* **`spaced-comment`** : Commentaires doivent être espacés
|
||
|
||
### Analyse préalable obligatoire et arbre des fichiers
|
||
|
||
Avant toute implémentation, une phase d’analyse est obligatoire et doit produire une représentation de l’arbre des fichiers pertinents.
|
||
|
||
Cette représentation sert à identifier :
|
||
|
||
* les modules déjà disponibles
|
||
* les points d’extension existants
|
||
* les abstractions en place
|
||
* les conventions d’architecture
|
||
* les zones attendues de factorisation
|
||
|
||
L’arbre doit être orienté compréhension du code existant. Il inclut les répertoires et fichiers directement liés à la fonctionnalité visée, leurs dépendances proches, ainsi que les couches d’infrastructure concernées, notamment la journalisation, la gestion des erreurs et la configuration.
|
||
|
||
Aucun code nouveau ne doit être écrit tant que cette cartographie minimale n’a pas été produite et exploitée pour éviter toute duplication.
|
||
|
||
### Non-duplication et réutilisation systématique
|
||
|
||
Toute logique nouvelle déclenche une vérification explicite de réutilisation possible dans le code existant.
|
||
|
||
Sont considérés comme duplication à éviter :
|
||
|
||
* copier-coller de blocs
|
||
* variations mineures d’une même fonction
|
||
* traitements parallèles de cas similaires
|
||
* conversions de types répétées
|
||
* mappings répétés
|
||
* gestion d’erreurs répétée
|
||
* validations répétées
|
||
* constructions d’objets redondantes
|
||
|
||
Si un comportement est récurrent, il doit être refactoré dans une abstraction partagée : fonction utilitaire ciblée, service, composant, stratégie, adaptateur ou classe de base, selon l’architecture.
|
||
|
||
Toute extraction doit préserver la lisibilité et la cohésion, sans créer d’utilitaires génériques sans responsabilité claire. Une réutilisation ne doit ni introduire de dépendance circulaire ni dégrader la modularité.
|
||
|
||
### Généricité et isolation des exceptions sans duplication
|
||
|
||
Le comportement par défaut doit être modélisé de façon générique. Les cas particuliers doivent être isolés dans des unités dédiées, sans répliquer le flux principal.
|
||
|
||
Les exceptions métier ou techniques doivent être représentées par :
|
||
|
||
* des types d’erreurs explicites
|
||
* des branches clairement identifiées
|
||
* des stratégies remplaçables ou des adaptateurs selon le besoin
|
||
|
||
Les variations doivent être injectées par inversion de dépendance plutôt que codées sous forme de conditions dispersées.
|
||
|
||
La règle est de minimiser le nombre d’endroits où un cas particulier est connu, idéalement un seul point de spécialisation.
|
||
|
||
### Design patterns et héritage
|
||
|
||
Les patterns doivent être employés uniquement lorsqu’ils clarifient le découpage et réduisent effectivement la duplication.
|
||
|
||
Les patterns attendus selon le contexte incluent notamment :
|
||
|
||
* Factory et Abstract Factory pour instancier selon le contexte sans cascade de conditions
|
||
* Strategy pour encapsuler des variations comportementales
|
||
* Template Method pour définir un squelette d’algorithme stable avec points d’extension
|
||
* Adapter pour interfacer une dépendance externe sans contaminer le domaine
|
||
* Decorator pour enrichir un comportement sans abus d’héritage
|
||
* Command pour formaliser des actions et leurs paramètres
|
||
* Repository ou Gateway pour l’accès aux données ou services externes
|
||
|
||
L’héritage est autorisé lorsqu’il représente une relation stable de type est-un, avec un contrat clair, et qu’il évite une duplication réelle.
|
||
|
||
Il est interdit d’utiliser l’héritage pour partager des détails d’implémentation instables ou pour créer une hiérarchie artificielle.
|
||
|
||
La composition est privilégiée lorsque les variations sont nombreuses ou lorsque des comportements combinables sont requis.
|
||
|
||
Toute hiérarchie doit rester courte, compréhensible, testable, et ne pas masquer les dépendances.
|
||
|
||
### Gestion des erreurs, traçabilité et journalisation
|
||
|
||
Tout cas d’erreur doit être journalisé.
|
||
|
||
Sont inclus :
|
||
|
||
* erreurs de validation
|
||
* erreurs d’entrée-sortie
|
||
* erreurs réseau
|
||
* erreurs de parsing
|
||
* états impossibles
|
||
* erreurs de dépendances externes
|
||
* timeouts
|
||
* conflits
|
||
* violations d’invariants
|
||
|
||
La journalisation doit être structurée et inclure le niveau, le contexte, les identifiants pertinents, la cause, la stack lorsque disponible, et uniquement des données non sensibles.
|
||
|
||
Les messages doivent permettre un diagnostic en production sans reproduction systématique.
|
||
|
||
Aucune erreur ne doit être ignorée silencieusement.
|
||
|
||
Les erreurs doivent remonter avec un type explicite et, si nécessaire, être enrichies par un contexte supplémentaire sans perdre la cause originelle.
|
||
|
||
Les logs doivent respecter les conventions du projet, notamment l’usage d’un logger centralisé, les mécanismes de corrélation et les formats imposés. L’usage direct de `console.log` est interdit si un système de journalisation est déjà en place.
|
||
|
||
### Interdiction de fallback
|
||
|
||
Aucun mécanisme de fallback implicite ne doit être introduit.
|
||
|
||
Sont considérés comme fallback interdits :
|
||
|
||
* l’utilisation de valeurs par défaut pour masquer une erreur
|
||
* l’attrapage d’une erreur suivi d’une poursuite silencieuse
|
||
* le déclenchement d’une voie alternative non explicitement spécifiée
|
||
* toute dégradation silencieuse de la qualité, de la sécurité ou de la cohérence
|
||
|
||
Si un comportement alternatif est requis fonctionnellement, il doit être explicitement défini comme un chemin nominal, avec des conditions d’activation claires, un typage explicite et une observabilité complète.
|
||
|
||
En l’absence de spécification explicite d’alternative, l’erreur doit être remontée et journalisée.
|
||
|
||
### Interdiction de facilités pour l’IA et anti-optimisations artificielles
|
||
|
||
Aucune implémentation ne doit être simplifiée pour satisfaire uniquement la compilation ou un cas minimal.
|
||
|
||
Sont interdits :
|
||
|
||
* stubs durables
|
||
* hacks temporaires laissés en place
|
||
* branches mortes
|
||
* TODO structurants non résolus
|
||
* implémentations partielles non signalées
|
||
* comportements best effort non spécifiés
|
||
|
||
L’optimisation pour l’IA elle-même est interdite. Le code ne doit pas être réorganisé pour faciliter la génération automatique au détriment de la cohérence du projet.
|
||
|
||
L’optimisation de performance n’est pas un objectif par défaut. Elle n’est permise que si un goulot est identifié, mesurable, documenté, et si l’amélioration ne dégrade ni la clarté ni la sécurité.
|
||
|
||
### Tests
|
||
|
||
Aucun test ad hoc ne doit être ajouté.
|
||
|
||
Sont considérés comme ad hoc :
|
||
|
||
* tests écrits pour forcer un comportement non contractuel
|
||
* tests dupliquant la logique de production
|
||
* tests utilisant des mocks excessifs pour faire passer un scénario
|
||
* tests ne respectant pas la stratégie existante du projet
|
||
|
||
Si le projet dispose d’une stratégie de tests, elle doit être strictement respectée.
|
||
|
||
Si une couverture supplémentaire est nécessaire, elle doit s’inscrire dans les patterns de tests existants, avec les fixtures, helpers et conventions en place, sans introduire une nouvelle infrastructure.
|
||
|
||
En l’absence de tests pour la zone concernée, aucune approche improvisée ne doit être introduite. Les points de vérification attendus peuvent être documentés, mais l’implémentation doit s’arrêter au code de production, sauf instruction contraire.
|
||
|
||
### Processus de modification du code
|
||
|
||
Toute modification doit être minimale en surface et maximale en cohérence.
|
||
|
||
Les changements doivent être localisés aux endroits architecturalement pertinents, sans dispersion.
|
||
|
||
L’architecture en couches du projet doit être respectée, qu’il s’agisse du domaine, de l’application, de l’infrastructure ou de la présentation.
|
||
|
||
Toute nouvelle dépendance doit être justifiée et alignée avec le socle existant.
|
||
|
||
Aucune bibliothèque ne doit être introduite si une capacité équivalente existe déjà dans le projet, sauf contrainte documentée.
|
||
|
||
Les noms, interfaces, types et contrats doivent être stables, explicites et orientés intention.
|
||
|
||
### Architecture logicielle et séparation des responsabilités
|
||
|
||
L'architecture du projet suit un modèle strict de séparation des responsabilités et d'isolation des couches. Toute modification doit respecter ces principes architecturaux fondamentaux.
|
||
|
||
#### Persistance des données
|
||
|
||
* **IndexedDB comme source de vérité locale** : Toutes les données sont persistées dans IndexedDB côté utilisateur. IndexedDB constitue la source de vérité locale pour toutes les données de l'application.
|
||
|
||
* **IndexedDB en lecture uniquement pour l'interface** : L'interface utilisateur (composants React, pages) utilise uniquement IndexedDB en lecture. Aucune écriture directe dans IndexedDB ne doit être effectuée depuis l'interface utilisateur.
|
||
|
||
* **Écritures via le réseau Nostr** : Toutes les écritures et mises à jour de données passent par le réseau Nostr. L'interface ne doit jamais écrire directement dans IndexedDB.
|
||
|
||
* **Statut de publication** : Toute écriture en base de données (IndexedDB) doit inclure un statut `published` qui permet de gérer ultérieurement la publication (ok/ko). Ce statut permet de suivre l'état de synchronisation et de publication des données.
|
||
|
||
#### Service Workers et tâches de fond
|
||
|
||
* **Service Workers pour les tâches de fond** : Toutes les tâches de fond sur les données sont effectuées avec des Service Workers. Les Service Workers gèrent la synchronisation, la mise à jour et le traitement asynchrone des données.
|
||
|
||
* **Service Worker pour les notifications** : Un Service Worker alimente la table des notifications. Il surveille les événements et met à jour IndexedDB avec les nouvelles notifications.
|
||
|
||
* **Détection indépendante des changements** : Le Service Worker pour les notifications détecte les changements de manière indépendante. Il n'est pas dépendant du service d'écriture et ne reçoit pas d'événements directs de celui-ci. Il surveille IndexedDB et détecte les nouvelles notifications par lui-même.
|
||
|
||
* **Service de lecture des notifications** : Les notifications sont lues par un service dédié qui détecte les nouvelles notifications dans la base de données (IndexedDB). Ce service est séparé du Service Worker qui alimente les notifications.
|
||
|
||
#### Web Workers et écritures
|
||
|
||
* **Web Worker d'écriture** : Un Web Worker dédié gère toutes les écritures et modifications dans IndexedDB. L'interface utilisateur ne doit jamais écrire directement dans IndexedDB, mais doit passer par ce Web Worker.
|
||
|
||
* **Accès aux données** : Le Web Worker d'écriture reçoit les données complètes, pas seulement les modifications. Les données partielles ou différentielles ne doivent pas être utilisées.
|
||
|
||
* **Transactions multi-tables** : Le Web Worker gère les transactions multi-tables via plusieurs transactions. La logique de découpage des transactions est gérée côté Web Worker, pas côté appelant.
|
||
|
||
* **Synchronisation et gestion des conflits** : Le Web Worker est conçu pour gérer une pile d'écritures. Il traite les écritures de manière séquentielle pour éviter les conflits lorsque plusieurs écritures arrivent simultanément. Aucune écriture ne doit contourner cette pile.
|
||
|
||
* **Service de gestion des écritures** : Un service gère les écritures/mises à jour vers les WebSockets/API et vers le Web Worker d'écriture. Ce service orchestre la communication entre l'interface, le réseau (Nostr/WebSockets) et le Web Worker d'écriture.
|
||
|
||
* **Orchestration** : Le service de gestion des écritures coordonne le flux WebSockets → Web Worker → IndexedDB. Il orchestre les écritures réseau et locales de manière indépendante.
|
||
|
||
* **Ordre des opérations** : Les écritures réseau et locales sont effectuées en parallèle et de manière indépendante. Il n'y a pas d'ordre imposé entre l'écriture réseau et l'écriture locale.
|
||
|
||
* **Gestion des erreurs** : Si le réseau échoue mais que l'écriture locale réussit, aucune action immédiate n'est requise. Un autre Service Worker réessaiera la publication ultérieurement en se basant sur le statut `published` des données en IndexedDB.
|
||
|
||
#### WebSockets et communication
|
||
|
||
* **Service de gestion des WebSockets** : Les WebSockets sont gérés par un service dédié qui communique avec les Service Workers. Ce service isole la logique de communication WebSocket et permet une gestion centralisée des connexions.
|
||
|
||
* **Rôle principal et secondaires** : Le service WebSocket a pour rôle principal la gestion des connexions. Ses rôles secondaires incluent le routage des messages et la gestion de l'état de connexion.
|
||
|
||
* **Communication avec les Service Workers** : La communication entre le service WebSocket et les Service Workers s'effectue via `postMessage`. Aucun autre mécanisme de communication ne doit être utilisé.
|
||
|
||
* **Gestion des reconnexions** : Le service WebSocket doit gérer les reconnexions automatiques et maintenir l'état de connexion. Les reconnexions doivent être transparentes pour les Service Workers.
|
||
|
||
* **Séparation des responsabilités** : Le service WebSocket ne doit pas écrire directement dans IndexedDB. Il communique avec les Service Workers qui gèrent la persistance.
|
||
|
||
#### Principes de respect de l'architecture
|
||
|
||
Toute modification doit respecter ces principes :
|
||
|
||
* **Pas d'écriture directe dans IndexedDB depuis l'interface** : L'interface utilisateur ne doit jamais écrire directement dans IndexedDB. Toutes les écritures passent par le réseau Nostr et le Web Worker d'écriture.
|
||
|
||
* **Séparation stricte des couches** : Les couches doivent rester isolées :
|
||
|
||
* Interface utilisateur (React) : Lecture IndexedDB uniquement
|
||
* Service de gestion des écritures : Orchestration des écritures réseau et Web Worker
|
||
* Web Worker d'écriture : Écritures dans IndexedDB
|
||
* Service Workers : Tâches de fond, synchronisation, notifications
|
||
* Service WebSocket : Communication réseau avec Service Workers
|
||
|
||
* **Statut de publication obligatoire** : Toute écriture en base doit inclure un statut `published` pour le suivi de la publication.
|
||
|
||
* **Pas de contournement** : Aucun contournement de cette architecture ne doit être introduit, même pour des cas particuliers. Les exceptions doivent être gérées dans le cadre de cette architecture.
|
||
|
||
### Validation et précaution obligatoires
|
||
|
||
Avant toute implémentation ou modification, certaines décisions critiques doivent être validées explicitement par l'utilisateur.
|
||
|
||
#### Validation des choix de design
|
||
|
||
Tous les choix de design architecturaux, d'interface utilisateur ou d'expérience utilisateur doivent être validés avant implémentation.
|
||
|
||
Sont concernés :
|
||
|
||
* **Architecture** : Choix de patterns, structure de modules, organisation des couches
|
||
* **Interface utilisateur** : Disposition des composants, flux de navigation, interactions utilisateur
|
||
* **Expérience utilisateur** : Parcours utilisateur, workflows, processus métier
|
||
* **Intégrations** : Choix d'API externes, protocoles de communication, formats d'échange
|
||
* **Performance** : Stratégies d'optimisation, mécanismes de cache, techniques de chargement
|
||
|
||
Aucune implémentation ne doit être commencée sans validation explicite des choix de design proposés.
|
||
|
||
#### Validation des modifications du modèle de données
|
||
|
||
Toute modification affectant le modèle de données, la structure de la base de données ou les schémas de données doit être validée avant implémentation.
|
||
|
||
Sont concernés :
|
||
|
||
* **Schémas de base de données** : Ajout, modification ou suppression de tables, colonnes, index, contraintes
|
||
* **Types de données** : Modifications de types, ajout de champs, changements de structure
|
||
* **Relations** : Ajout ou modification de relations entre entités, clés étrangères
|
||
* **Migrations** : Scripts de migration de base de données, transformations de données
|
||
* **Contrats d'API** : Modifications des structures de données échangées via API
|
||
* **Formats de stockage** : Changements de format de fichiers, structures JSON, schémas de validation
|
||
|
||
**Toute modification du modèle de données doit être documentée avec :**
|
||
|
||
* L'impact sur les données existantes
|
||
* Les migrations nécessaires
|
||
* Les risques de régression
|
||
* Les stratégies de rollback
|
||
|
||
Aucune modification du modèle de données ne doit être implémentée sans validation explicite.
|
||
|
||
#### Validation des commits et publications
|
||
|
||
Tous les commits et publications doivent être validés avant exécution.
|
||
|
||
**Commits :**
|
||
|
||
* Tous les commits doivent être présentés avec leur message structuré avant validation
|
||
* Aucun commit ne doit être effectué sans validation explicite
|
||
* Les commits doivent être atomiques et logiques
|
||
* Les commits doivent respecter le format structuré défini dans les règles de commits
|
||
|
||
**Publications :**
|
||
|
||
* Toutes les publications (push, merge, release) doivent être validées avant exécution
|
||
* Les publications vers les branches principales (main, master, production) nécessitent une validation explicite
|
||
* Les déploiements doivent être validés avant exécution
|
||
|
||
Aucun commit ou publication ne doit être effectué automatiquement sans validation.
|
||
|
||
#### Validation des modifications des contrôles qualité et consignes
|
||
|
||
Toute modification des règles de qualité, des contrôles de linting, des configurations ESLint, des règles TypeScript ou des consignes à l'IA doit être validée avant application.
|
||
|
||
Sont concernés :
|
||
|
||
* **Règles de linting** : Ajout, modification ou suppression de règles ESLint
|
||
* **Configuration TypeScript** : Modifications de `tsconfig.json`, règles de compilation
|
||
* **Règles de qualité** : Modifications des fichiers de règles (`.cursor/rules/`, `quality.mdc`, etc.)
|
||
* **Consignes à l'IA** : Modifications des instructions pour l'IA, changements de workflow
|
||
* **Tests** : Modifications des stratégies de test, ajout ou suppression de frameworks de test
|
||
* **CI/CD** : Modifications des pipelines, des scripts de déploiement, des vérifications automatiques
|
||
|
||
Ces modifications ont un impact systémique sur tout le projet et doivent être validées explicitement avant application.
|
||
|
||
#### Processus de validation
|
||
|
||
Le processus de validation doit suivre ces étapes :
|
||
|
||
1. **Proposition** : Présenter clairement les choix ou modifications proposés avec :
|
||
* Le contexte et les motivations
|
||
* Les alternatives considérées
|
||
* Les impacts attendus
|
||
* Les risques identifiés
|
||
|
||
2. **Attente de validation** : Attendre explicitement la validation de l'utilisateur avant de procéder
|
||
|
||
3. **Documentation** : Documenter les choix validés dans la documentation appropriée (`docs/`, `features/`, `fixKnowledge/`)
|
||
|
||
4. **Implémentation** : Procéder à l'implémentation uniquement après validation explicite
|
||
|
||
Aucune action ne doit être entreprise en supposant une validation implicite ou en anticipant une réponse.
|
||
|
||
### Documentation et contrats
|
||
|
||
Les fonctions publiques, classes et modules introduits doivent être auto-descriptifs par leur nommage et leur typage.
|
||
|
||
Les commentaires ne doivent pas répéter le code. Ils doivent expliciter :
|
||
|
||
* les invariants
|
||
* les hypothèses
|
||
* les contrats
|
||
* les cas limites
|
||
* les raisons d’un choix de conception
|
||
|
||
Les invariants critiques doivent être vérifiés explicitement. En cas de violation, une erreur typée et journalisée doit être levée.
|
||
|
||
Les interfaces doivent éviter les paramètres optionnels fourre-tout. Les objets de configuration typés sont préférés, avec des champs requis ou optionnels clairement justifiés.
|
||
|
||
### Optimisation et mise à jour systématique de la documentation
|
||
|
||
La documentation doit être optimisée et mise à jour systématiquement lors de toute modification du code.
|
||
|
||
**Règles obligatoires** :
|
||
|
||
* **Fidélité au code** : La documentation doit refléter fidèlement l’état actuel du code. Toute modification de code doit entraîner une mise à jour de la documentation correspondante.
|
||
|
||
* **Éviter les répétitions** : Fusionner les documents redondants. Un même concept ne doit être documenté qu’une seule fois, dans le document le plus approprié.
|
||
|
||
* **Centralisation** : La documentation technique doit être centralisée dans `docs/` et les fonctionnalités dans `features/`. Éviter la dispersion de l’information.
|
||
|
||
* **Mise à jour lors des modifications** : Lors de toute modification de code, fonctionnalité ou architecture :
|
||
* Vérifier si la documentation existante est obsolète
|
||
* Mettre à jour ou supprimer les sections obsolètes
|
||
* Fusionner les documents similaires
|
||
* Supprimer les documents redondants
|
||
|
||
* **Optimisation continue** :
|
||
* Supprimer les documents obsolètes (code supprimé, fonctionnalités remplacées)
|
||
* Fusionner les documents qui se chevauchent
|
||
* Maintenir une structure claire et navigable
|
||
* Éviter les doublons entre `docs/` et `features/`
|
||
|
||
* **Vérification** : Avant de finaliser une modification, vérifier que la documentation est à jour et cohérente avec le code.
|
||
|
||
### Critères d’acceptation implicites
|
||
|
||
Le code final doit :
|
||
|
||
* compiler sans contournement
|
||
* respecter le linting sans suppression
|
||
* réduire, et non augmenter, la duplication
|
||
* introduire des abstractions justifiées et localisées
|
||
* isoler les cas particuliers sans répliquer le flux principal
|
||
* être observable en erreur via des logs structurés
|
||
* ne contenir aucun fallback implicite
|
||
* ne pas introduire de tests ad hoc
|
||
|
||
## Conclusion
|
||
|
||
Ces consignes constituent un cadre de production strict. Elles imposent une analyse préalable via un arbre des fichiers, un typage TypeScript sans contournement, une non-duplication systématique, une architecture fondée sur des abstractions pertinentes, l’usage raisonné de patterns, une journalisation exhaustive des erreurs et un refus explicite des fallbacks implicites. Appliquées rigoureusement, elles conduisent à un code TypeScript robuste, évolutif et cohérent avec un référentiel de qualité de haut niveau.
|
||
|
||
## Analytics
|
||
|
||
* Ne pas mettre d'analytics
|
||
* Statistiques profil : pas de vues/paiements/revenus par article, agrégats et affichage
|
||
|
||
## Cache
|
||
|
||
* Pas de mémorisation, pas de cache
|
||
|
||
## Accessibilité
|
||
|
||
* ARIA
|
||
* clavier
|
||
* contraste
|
||
|
||
## Expérience utilisateur
|
||
|
||
### Minimisation du nombre de clics
|
||
|
||
Toute interface utilisateur doit être conçue pour minimiser le nombre de clics nécessaires à l'accomplissement des actions principales.
|
||
|
||
**Principes à respecter :**
|
||
|
||
* **Actions directes** : Les actions fréquentes doivent être accessibles directement, sans navigation intermédiaire
|
||
* **Regroupement fonctionnel** : Regrouper les actions liées pour éviter les clics de navigation inutiles
|
||
* **Formulaires optimisés** : Permettre la validation et la soumission en un seul clic lorsque possible
|
||
* **Navigation efficiente** : Éviter les parcours multi-étapes si une solution en une étape est possible
|
||
* **Actions contextuelles** : Proposer les actions pertinentes directement dans le contexte où l'utilisateur se trouve
|
||
* **Raccourcis clavier** : Fournir des raccourcis clavier pour les actions fréquentes afin de réduire le nombre de clics
|
||
|
||
**À éviter :**
|
||
|
||
* Formulaires nécessitant plusieurs clics de validation intermédiaires
|
||
* Navigation profonde pour accéder aux fonctionnalités principales
|
||
* Actions cachées derrière plusieurs menus ou modals
|
||
* Parcours utilisateur avec étapes redondantes
|
||
|
||
## Open Source
|
||
|
||
Le projet est open source et hébergé sur Gitea auto-hébergé. Toutes les contributions doivent respecter les principes open source suivants.
|
||
|
||
### Principes open source
|
||
|
||
* **Transparence** : Tous les changements doivent être traçables, documentés et accessibles publiquement
|
||
* **Collaboration** : Le code doit être conçu pour faciliter les contributions externes
|
||
* **Documentation** : Toute fonctionnalité ou modification doit être documentée pour les contributeurs externes
|
||
* **Standards ouverts** : Utiliser des standards ouverts et éviter les dépendances propriétaires non documentées
|
||
* **Licence MIT** : Le code doit respecter la licence MIT et être compatible avec cette licence
|
||
|
||
### Contribution et workflow open source
|
||
|
||
* **Commits systématiques** : Tous les changements doivent être commités avec des messages structurés
|
||
* **Format de commit** : Les commits doivent suivre le format défini dans CONTRIBUTING.md avec sections Motivations, Root causes, Correctifs, Evolutions, Pages affectées
|
||
* **Pull Requests** : Tous les changements doivent passer par des Pull Requests sur Gitea, même pour les modifications internes
|
||
* **Documentation des changements** : Toute modification doit être documentée dans `fixKnowledge/` (pour les corrections) ou `features/` (pour les évolutions)
|
||
* **Traçabilité** : Chaque modification doit être liée à une issue ou une PR sur Gitea si applicable
|
||
|
||
### Qualité pour contributions externes
|
||
|
||
* **Code lisible** : Le code doit être compréhensible par des contributeurs externes sans connaissance préalable du contexte interne
|
||
* **Commentaires explicatifs** : Les choix de conception non évidents doivent être commentés
|
||
* **Documentation à jour** : La documentation doit toujours refléter l'état actuel du code
|
||
* **Exemples et guides** : Fournir des exemples d'utilisation et des guides pour les nouvelles fonctionnalités
|
||
* **Tests et validation** : Le code doit être validé et testable par des contributeurs externes
|
||
|
||
### Gestion des contributions
|
||
|
||
* **Respect du Code of Conduct** : Tous les contributeurs doivent respecter le CODE_OF_CONDUCT.md
|
||
* **Review process** : Toutes les contributions doivent être revues avant merge
|
||
* **Feedback constructif** : Fournir un feedback constructif et respectueux sur les contributions
|
||
* **Attribution** : Créditer les contributeurs dans les commits et la documentation
|
||
|
||
### Sécurité open source
|
||
|
||
* **Reporting de vulnérabilités** : Suivre le processus défini dans SECURITY.md
|
||
* **Pas de secrets** : Aucun secret, clé API ou credential ne doit être commité
|
||
* **Dépendances sécurisées** : Vérifier la sécurité des dépendances avant ajout
|
||
* **Audit de sécurité** : Les changements de sécurité doivent être documentés et audités
|
||
|
||
### Repository et infrastructure
|
||
|
||
* **Repository Gitea** : <https://git.4nkweb.com/4nk/story-research-zapwall>
|
||
* **Templates** : Utiliser les templates d'issues et de PR dans `.gitea/`
|
||
* **Labels et organisation** : Utiliser les labels appropriés pour organiser les issues et PRs
|
||
* **Branches** : Respecter la convention de nommage des branches (feature/, fix/, etc.)
|
||
|
||
## Commits systématiques
|
||
|
||
**Règle absolue** : Tous les changements doivent être commités immédiatement après leur réalisation.
|
||
|
||
### Obligation de commit
|
||
|
||
* **Pas de modifications non commitées** : Aucune modification ne doit rester non commitée
|
||
* **Commits atomiques** : Chaque commit doit représenter une modification logique et complète
|
||
* **Commits fréquents** : Commiter régulièrement, pas seulement à la fin d'une session
|
||
* **Pas de stash prolongé** : Éviter de laisser des modifications en stash sans les commiter
|
||
|
||
### Format de commit obligatoire
|
||
|
||
Tous les commits doivent suivre ce format structuré :
|
||
|
||
```text
|
||
Titre court et descriptif
|
||
|
||
**Motivations:**
|
||
- Raison de la modification
|
||
|
||
**Root causes:**
|
||
- Cause racine du problème (si applicable)
|
||
|
||
**Correctifs:**
|
||
- Ce qui a été corrigé
|
||
|
||
**Evolutions:**
|
||
- Nouvelles fonctionnalités ou améliorations
|
||
|
||
**Pages affectées:**
|
||
- Liste des fichiers/modules modifiés
|
||
```
|
||
|
||
### Processus de commit
|
||
|
||
1. **Avant chaque commit** :
|
||
* Vérifier que le code compile (`npm run type-check`)
|
||
* Vérifier le linting (`npm run lint`)
|
||
* Vérifier que les modifications sont complètes et fonctionnelles
|
||
|
||
2. **Création du commit** :
|
||
* Utiliser `git add` pour les fichiers modifiés
|
||
* Créer un commit avec le format structuré
|
||
* Ne pas utiliser `--no-verify` sauf cas exceptionnel documenté
|
||
|
||
3. **Après le commit** :
|
||
* Vérifier que le commit a bien été créé (`git log`)
|
||
* Documenter dans `fixKnowledge/` ou `features/` si nécessaire
|
||
|
||
### Exceptions
|
||
|
||
Les seules exceptions à la règle de commit immédiat sont :
|
||
|
||
* **Modifications en cours de test** : Si une modification nécessite des tests manuels avant commit, elle doit être commitée dès que les tests sont validés
|
||
* **Refactoring en plusieurs étapes** : Les refactorings complexes peuvent être commités par étapes logiques
|
||
* **Documentation en cours** : La documentation peut être commitée séparément du code si elle est volumineuse
|
||
|
||
Dans tous les cas, aucun changement ne doit rester non commité plus de quelques heures.
|
||
|
||
### Intégration avec le workflow open source
|
||
|
||
* **Commits avant PR** : Tous les commits doivent être faits avant la création d'une Pull Request
|
||
* **Commits dans les PRs** : Les commits dans une PR doivent être organisés et logiques
|
||
* **Squash si nécessaire** : Les commits peuvent être squashés dans une PR si cela améliore la lisibilité, mais chaque commit individuel doit rester valide
|
||
* **Historique propre** : Maintenir un historique Git propre et lisible pour les contributeurs externe
|