> 🧠 Ces règles s’appliquent **exclusivement au Serenity CoreBundle**.

# Repository Guidelines

## Section 1 – Identité de l’agent
- **Nom** : Serenity Core Bundle.
- **Rôle** : socle transversal qui expose services, configuration et contrats communs à tout l’écosystème Serenity.
- **Spécialité** : fournir une base Symfony ≥ 7.3 préconfigurée, prête à accueillir des fonctionnalités partagées et à stabiliser les dépendances critiques.

## Section 2 – Contexte du bundle
- Le bundle structure le code selon les couches DDD (`Domain`, `Application`, `Infrastructure`, `Presentation`) pour clarifier les responsabilités de chaque feature.
- `config/packages/auto/` livre la configuration par défaut des composants Symfony activés sur tous les projets Serenity (security, messenger, rate limiter, etc.).
- `src/` regroupe les briques nécessaires à une application complexe : services de navigation, notifications, sécurité, valeurs métier et traits réutilisables.
- Les ressources communes (`templates/`, `assets/`, `translations/`, `fixtures/`) garantissent une expérience cohérente sur les interfaces et les données de démonstration.
- Le bundle sert de fondation aux autres modules Serenity ; toute évolution doit rester compatible avec ce rôle de base.

## Section 3 – Vérifications automatiques avant et après modification du code

### ⚙️ Préparation avant contribution

Avant toute modification du code source du **Serenity CoreBundle**, l’agent doit **vérifier l’état du dépôt** afin de s’assurer qu’aucun changement local n’est en attente de commit.
L’objectif est d’éviter tout écrasement ou conflit avant l’écriture de nouvelles fonctionnalités.

#### Étapes à suivre

1. Exécuter la commande :

   ```bash
   git status
   ```

2. Si des fichiers modifiés, ajoutés ou supprimés apparaissent, **l’agent doit poser la question suivante** :

   > ⚠️ **Des modifications locales non commitées ont été détectées.**
   > Voulez-vous les commiter avant de continuer ? (**oui/non**)

3. Si la réponse est **oui**, l’agent doit proposer de créer un commit clair et cohérent suivant le format :

   ```text
   [type]: [description courte et explicite]
   ```

   **Exemples :**
    - `fix: correction du mapping Doctrine du User`
    - `feat: ajout du service de notification système`
    - `refactor: simplification du Repository User`

4. Si la réponse est **non**, la modification peut se poursuivre, mais l’agent doit **prévenir du risque de perte ou de conflit**.

---

### 🧹 Vérification de la qualité du code après modification

Une fois les modifications apportées, l’agent doit effectuer **trois vérifications automatiques** :
**formatage**, **analyse statique**, et **tests unitaires**.
Ces étapes garantissent la stabilité, la propreté et la conformité du CoreBundle.

#### 1️⃣ Vérification et correction du code (PHP CS Fixer)

Le code doit être formaté selon la configuration du bundle.
Exécuter :

```bash
../../../vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.php
```

Cette commande formate automatiquement tous les fichiers du bundle selon les conventions PSR et Serenity.

---

#### 2️⃣ Analyse statique (PHPStan)

L’agent doit lancer une analyse statique **non parallèle** pour détecter les erreurs de typage ou de conception.

```bash
../../../vendor/bin/phpstan analyse --configuration ../../../phpstan.dist.neon --no-parallel
```

- Si des erreurs sont détectées, l’agent doit les **corriger automatiquement si possible**, ou les signaler explicitement avec une description claire.
- Aucune modification ne doit être validée tant que PHPStan ne renvoie pas un **niveau de confiance maximal (0 erreur)**.

---

#### 3️⃣ Exécution des tests unitaires

Enfin, les tests du bundle doivent être exécutés pour garantir la non-régression :

```bash
../../../vendor/bin/phpunit --bootstrap ../../../vendor/autoload.php --do-not-cache-result tests
```

- Si des tests échouent, l’agent doit **stopper immédiatement** la livraison du code et afficher un rapport d’échec clair.
- Une fois tous les tests passés avec succès, l’agent peut valider la tâche comme **terminée et conforme**.

---

### ✅ Résumé du cycle complet

1. Vérifier l’état du dépôt (`git status`)
2. Demander si les modifications doivent être commit avant de poursuivre
3. Écrire le code
4. Lancer successivement :
    - **PHP CS Fixer** → formatage
    - **PHPStan** → analyse statique
    - **PHPUnit** → tests unitaires
5. Ne valider aucune modification tant que toutes les vérifications ne sont pas **vertes**

## Section 4 – Règles Serenity (architecture, code, qualité, tests)

### 🧩 Architecture
- Le **CoreBundle** adopte une organisation inspirée du **Domain-Driven Design (DDD)**, structurée selon les couches :
  `Domain`, `Application`, `Infrastructure`, `Presentation`.
- Interdiction de toute **dépendance descendante** : la couche `Domain` ne dépend jamais d’`Application` ni d’`Infrastructure`.
- Utilisation des **DTOs**, **CommandHandlers** et **Repositories** pour organiser la logique applicative et les échanges entre couches.
- Les **entités de domaine** doivent être **autonomes**, mais un **couplage léger** à certaines briques techniques est **autorisé** :
    - utilisation de la **classe `Uuid`** (`Symfony\Component\Uid\Uuid`),
    - usage des **attributs de validation Symfony** (`#[Assert\...]`),
    - présence d’**annotations ou types Doctrine** lorsque cela simplifie la persistance des entités.
      Ces dépendances doivent rester limitées et ne pas introduire de logique d’infrastructure.
- L’architecture privilégie une approche **modulaire** : chaque fonctionnalité est isolée dans des **composants Twig et UX Live** réutilisables.
- Les composants UX Live du Core (ex. : `FormComponent`) servent de base à la construction de formulaires dynamiques et interactifs dans tous les modules Serenity.

---

#### 🧩 Design Patterns & Symfony 7
- Le **CoreBundle** encourage l’utilisation systématique des **Design Patterns** (Strategy, Factory, Observer, Adapter, etc.) pour une architecture claire et extensible.
- Profitez de la **puissance native de Symfony 7** pour les implémenter :
    - Utilisez `AutowireIterator` pour appliquer le **design pattern Strategy**, en permettant l’injection dynamique de plusieurs implémentations d’une même interface.
    - Utilisez les **autoconfigurations et autowiring par interface** pour simplifier la maintenance et la substitution de comportements.
- Lors de la création d’une **interface**, veillez à :
    1. Déclarer un **alias dans `services.yaml`** afin d’associer explicitement l’interface à une implémentation par défaut.
       Exemple :
       ```yaml
       # config/services.yaml
       Serenity\CoreBundle\Service\MailerInterface: '@Serenity\CoreBundle\Service\SymfonyMailer'
       ```
    2. Documenter dans la classe la logique de remplacement possible pour d’autres bundles.
    3. Favoriser les **interfaces métier** (dans `Domain`) plutôt que les classes concrètes dans les dépendances des services.
- Objectif : exploiter au maximum les mécanismes modernes du container Symfony (autowiring, attributes, service decoration) pour maintenir une **architecture propre, découplée et évolutive**.

---

### 💻 Code PHP
- Suivez les **normes de codage PSR-1, PSR-2, PSR-4 et PSR-12**.
  Ces standards assurent une cohérence et une interopérabilité entre tous les bundles Serenity.
- Code conforme aux **règles PHP CS Fixer** et analysé statiquement via `phpstan`.
- Utilisation obligatoire du **typage strict** :
  `declare(strict_types=1);` en en-tête de chaque fichier PHP.
- **Utiliser au maximum les nouvelles syntaxes et fonctionnalités** de **PHP 8.3 et 8.4** :
    - propriétés readonly et promotion de propriétés dans les constructeurs,
    - enums et types d’union/intersection,
    - null-safe operator (`?->`),
    - match expressions,
    - attributs (`#[...]`),
    - class constants visibility,
    - json_validate, typed class constants, etc.
      L’objectif est d’écrire un code moderne, concis et sécurisé.
- Interdiction d’utiliser du **code obsolète** ou des composants **inférieurs à Symfony 7.3 et PHP 8.3**.
- Les classes doivent être **finales** sauf si une extension est prévue explicitement.
- Les dépendances sont injectées via le **constructeur** (pas de conteneur global ni de service locator).
- Les exceptions doivent être typées et explicites (`DomainException`, `ValidationException`, etc.).
- Le code doit rester **prévisible, déterministe et testable**, sans effets de bord non contrôlés.
- **Organisation du code :**
    - Déclarer toutes les **propriétés** avant les **méthodes**.
    - Ordonner les méthodes selon la visibilité : **public → protected → private**.
    - Dans les **entités Doctrine**, déclarer les relations dans l’ordre suivant :
      **OneToOne → ManyToOne → OneToMany → ManyToMany**.
      Cet ordre favorise la lisibilité, la cohérence et la logique du modèle de données.
- **Conventions de nommage :**
    - `camelCase` → pour les **variables**, **propriétés** et **noms de méthodes**.
    - `snake_case` → pour les **fichiers de configuration**, les **routes** et les **templates Twig**.
    - `SCREAMING_SNAKE_CASE` → pour les **constantes**.
    - Les **classes** et **interfaces** utilisent le **PascalCase** (`FormComponent`, `UserRepositoryInterface`).
- **Conventions de retour :**
    - Utiliser `return null;` pour les **retours nullables** (`?Type`).
    - Utiliser `return;` pour les **fonctions `void`**.
    - Ne jamais omettre explicitement un `return` final lorsqu’un retour est attendu.

---

### 🎨 Templates Twig
- Le rendu visuel repose sur des **composants Twig** modulaires, déclarés via `@AsTwigComponent` ou `@AsLiveComponent`.
- Chaque composant Twig est autonome : un template, une logique PHP associée, et éventuellement un fichier de style ou de script.
- Les noms de templates suivent la convention :
  `@components/SerenityCore/<NomComposant>/<template>.html.twig`
- Le style et le comportement doivent être encapsulés : aucune dépendance à des templates globaux sauf conventions communes (`base.html.twig`, macros utilitaires, etc.).
- Toutes les **icônes** utilisées dans les templates doivent provenir de la librairie **Lucide Icons**,
  pour garantir une cohérence visuelle et une intégration fluide avec les composants UX.
#### 📁 Organisation du dossier `/templates`
Le dossier `/templates` du CoreBundle suit une structure claire et modulaire :

- **`/components`**
  Contient les **composants Twig et UX Live** utilisés dans les vues.
  Chaque composant est isolé dans son propre sous-dossier et peut inclure un template, une classe PHP et un fichier de style ou script associé.
- **`/extends`**
  Permet de **surcharger ou personnaliser** le rendu par défaut de certains éléments (ex. formulaires ou champs).
  Exemple :
- **`/layout`**
  Contient les **templates de page** ou gabarits globaux (`base.html.twig`, `dashboard.html.twig`, `login.html.twig`, etc.).
  Ces layouts servent de structure de base pour l’intégration des composants et vues spécifiques.
Tous les templates doivent respecter une **indentation à 4 espaces**, des **blocs explicites** (`block content`, `block title`, etc.) et une **nomenclature cohérente** avec la structure du CoreBundle.
---

### 🎨 CSS et JavaScript
- Le CoreBundle adopte une approche **composantielle** pour le front :
  chaque composant dispose de son propre style et, si nécessaire, de son script.
- Le CSS suit une **convention BEM légère** et privilégie **Tailwind CSS** pour la rapidité de prototypage et la cohérence visuelle.
- Le JavaScript doit utiliser **Stimulus** (inclus via Symfony UX) pour les comportements interactifs légers,
  et **AlpineJS** pour enrichir l’expérience **UX/UI** avec une syntaxe simple et déclarative.
- Pour les composants dynamiques complexes, **Symfony UX Live Components** sont privilégiés.
- Aucun code JS inline dans les templates.
  Les comportements doivent être centralisés dans des contrôleurs Stimulus, Alpine ou des composants Live.

---

### 🧠 Bonnes pratiques globales
- Aucune **logique métier** ne doit se trouver dans les contrôleurs :
  ils orchestrent uniquement les cas d’usage (Application Layer).
- L’usage de Value Objects ou d’Enums est privilégié pour représenter les concepts métier,
  afin d’éviter les primitives génériques (string, int, etc.) et de renforcer la cohérence du domaine.
- Le code doit être clair, lisible et auto-documenté ; les commentaires servent à expliquer le *pourquoi*, jamais le *comment*.
- Les commits doivent rester petits, cohérents et décrits de manière explicite.

---

### 🧠 Analyse statique obligatoire (PHPStan, PHPCS Fixer, Prettier)

À **chaque modification de code**, qu’il s’agisse d’un fichier créé, modifié ou généré automatiquement,
il est **obligatoire d’exécuter PHPStan** afin de garantir la cohérence et la stabilité du bundle Serenity Core.

```bash
../../../vendor/bin/phpstan analyse --configuration ../../../phpstan.dist.neon
