Contexte du Refactoring Bidji - Point de Reprise

Dernière mise à jour : 2026-02-06 Statut du projet : Phase 1 terminée ✅

🎯 Objectif Global

Refactorer le système de génération de code Bidji (BidjicTask) pour remplacer le preprocessing fragile par replaceAll() par un système robuste et maintenable.

📊 État d’Avancement

✅ Ce Qui A Été Fait (Phase 1)

Fichiers Créés

1. doc/Refactoring.md (2000+ lignes)

   • Plan complet de refactoring en 4 phases
   • Analyse critique du système actuel
   • Proposition de nouvelle syntaxe
   • Code d’exemple complet pour Phase 2 et 3
   • Roadmap détaillée

2. doc/BidjicDirectives.md (800+ lignes)

   • Guide complet pour développeurs de templates
   • Documentation de 49 directives avec exemples
   • 4 exemples complets de génération de code
   • Section “Pièges Courants”
   • Guide de migration

3. doc/BidjicDirectivesReference.md (400+ lignes)

   • Référence technique rapide (“cheat sheet”)
   • Tableaux récapitulatifs
   • Ordre d’exécution par priorité
   • Statistiques : 42 actives, 7 deprecated

4. doc/Phase1-Inventaire-Complete.md

   • Rapport détaillé de Phase 1
   • Analyse des 49 directives
   • Problèmes identifiés
   • Recommandations pour Phase 2

5. src/test/java/org/bidji/preprocessor/BidjicPreprocessorTest.java (600+ lignes)

   • 60+ tests unitaires préparés
   • Prêts à être activés en Phase 2
   • Tests de non-régression

Connaissances Acquises

• 49 directives identifiées et documentées (42 actives + 7 deprecated)
• Problème critique : Ordre d’exécution des replaceAll() non documenté et fragile
• 7 directives deprecated à supprimer (aliases inutiles)
• Templates du projet n’utilisent pas les directives (ce sont des templates internes au framework)
• Code source problématique : BidjicTask.freemarkerize() lignes 1003-1072

🔴 Problèmes Identifiés

Critique

1. freemarkerize() fragile - 60+ replaceAll() sans validation, ordre implicite
2. Aucune validation - Directives inconnues = erreurs silencieuses
3. Impossible à débugger - Pas de logs de transformation

Moyen

4. 7 directives deprecated - Aliases inutiles (ex: property?kind_of_string)
5. Variables statiques - Non thread-safe (currentTask, PACKAGE, MODULE)
6. execute2() trop long - God method de 300+ lignes

📋 Prochaines Étapes - Phase 2

Tâches Prioritaires

1. Créer BidjicPreprocessor (🔴 Haute priorité)

Fichier : src/main/java/org/bidji/preprocessor/BidjicPreprocessor.java

Contenu :

• Système de règles avec priorités explicites
• Validation automatique de l’ordre
• Logs de transformation (mode debug)
• 60+ règles documentées

Code d’exemple : Voir doc/Refactoring.md section “Phase 2.1”

Temps estimé : 1-2 jours

2. Activer les Tests (🔴 Critique)

Fichier : src/test/java/org/bidji/preprocessor/BidjicPreprocessorTest.java

Actions :

• Décommenter les 60+ tests
• Vérifier qu’ils passent tous au vert
• Ajouter tests de performance si nécessaire

Temps estimé : 0.5 jour

3. Créer TemplateValidator (🟡 Moyenne priorité)

Fichier : src/main/java/org/bidji/preprocessor/TemplateValidator.java

Contenu :

• Détection de directives inconnues
• Warnings pour directives deprecated
• Vérification erreurs communes

Code d’exemple : Voir doc/Refactoring.md section “Phase 2.2”

Temps estimé : 1 jour

4. Intégrer dans BidjicTask (🔴 Haute priorité)

Fichier : src/main/java/org/bidji/taskdefs/BidjicTask.java

Modifications :

// AVANT (ligne ~1003)
private String freemarkerize(String templateContent) {
    String res = templateContent;
    // 60+ replaceAll()...
    return res;
}

// APRÈS
private String freemarkerize(String templateContent) {
    BidjicPreprocessor preprocessor = new BidjicPreprocessor();
    return preprocessor.preprocess(templateContent, verbose);
}

Temps estimé : 0.5 jour

5. Génération Auto de Doc (🟡 Moyenne priorité)

Action : Ajouter méthode printMarkdownReference() à BidjicPreprocessor

Intégration Ant :

<target name="bidji-doc-directives">
    <java classname="org.bidji.preprocessor.BidjicPreprocessor">
        <arg value="--markdown"/>
    </java>
</target>

Temps estimé : 0.5 jour

Livrables Phase 2

• BidjicPreprocessor.java (~300 lignes)
• TemplateValidator.java (~150 lignes)
• 60+ tests au vert
• Intégration dans BidjicTask
• Documentation auto-générée

Critères de Succès Phase 2

• ✅ Tous les tests passent
• ✅ Compatibilité 100% avec système actuel (aucun breaking change)
• ✅ Logs de transformation disponibles en mode verbose
• ✅ Warnings pour directives deprecated
• ✅ Documentation auto-générée
• ✅ Performance équivalente ou meilleure

📚 Fichiers Clés à Connaître

Documentation

• doc/Refactoring.md - Plan complet (LIRE EN PREMIER)
• doc/BidjicDirectives.md - Guide utilisateur
• doc/BidjicDirectivesReference.md - Référence rapide
• doc/Phase1-Inventaire-Complete.md - Rapport Phase 1
• doc/CONTEXTE-REFACTORING.md - Ce fichier (point de reprise)

Code Source à Modifier

• src/main/java/org/bidji/taskdefs/BidjicTask.java (lignes 1003-1072)

  • Méthode freemarkerize() à remplacer
  • Variables statiques à éliminer (Phase 4)
  • Méthode execute2() à décomposer (Phase 4)

• src/main/java/org/bidji/util/ModelHelper.java (500+ lignes)

  • À séparer en classes cohésives (Phase 4)

Tests

• src/test/java/org/bidji/preprocessor/BidjicPreprocessorTest.java
  • Tests prêts à activer en Phase 2

À Créer en Phase 2

• src/main/java/org/bidji/preprocessor/BidjicPreprocessor.java
• src/main/java/org/bidji/preprocessor/TemplateValidator.java

🔑 Informations Techniques Clés

Les 49 Directives (Résumé)

Ordre Critique

⚠️ nested?entity.@default_sort (priorité 110) DOIT être avant nested?entity (priorité 100)

Sinon :

// ❌ INCORRECT
"nested?entity" → transformé en "Model?api.get_entity(nested.@type)"
"nested?entity.@default_sort" → ne matche plus car déjà transformé !

// ✅ CORRECT
"nested?entity.@default_sort" → transformé d'abord
"nested?entity" → transformé ensuite

Variables Globales dans Templates

${bidji}          [# Modèle racine]
${entity}         [# Entité courante]
${Model}          [# Nom du modèle]
${Package}        [# Package extrait du chemin]
${Module}         [# Module extrait du chemin]
${Model?api}      [# Helper ModelHelper]

💡 Décisions Architecturales Prises

✅ Approche Retenue pour Phase 2

Preprocessing structuré avec système de règles :

• Chaque règle = Pattern + Remplacement + Description + Priorité
• Validation automatique de l’ordre au chargement de classe
• Logs optionnels pour debugging
• 100% de compatibilité backward

Alternative rejetée : Parser complet (trop complexe pour Phase 2)

✅ Approche Retenue pour Phase 3

Directives FreeMarker natives :

• Namespace clair : bidji.entity.*, bidji.property.*, bidji.ui.*
• Support dual (legacy + nouveau) pendant migration
• Validation par FreeMarker (erreurs claires)

Alternative rejetée : Garder le preprocessing éternellement

🎓 Leçons Apprises

1. Les templates internes n’utilisent pas les directives

   • Bidji est un framework, les directives sont pour les utilisateurs
   • Impossible d’analyser l’usage réel sans templates externes

2. Le preprocessing est plus fragile que prévu

   • 60+ replaceAll() dans un ordre implicite
   • Aucune validation ni logging
   • Bugs potentiels difficiles à détecter

3. Les directives sont bien conçues conceptuellement

   • Nommage cohérent
   • Séparation ? (query) vs .@ (attribut)
   • Bonne base pour nouvelle syntaxe

🚀 Comment Reprendre

Si vous reprenez demain

1. Relire ce fichier (CONTEXTE-REFACTORING.md)
2. Consulter doc/Refactoring.md section “Phase 2”
3. Commencer par créer BidjicPreprocessor.java

Si vous reprenez dans 1 semaine

1. Lire doc/Refactoring.md en entier (rappel du contexte)
2. Lire doc/Phase1-Inventaire-Complete.md (ce qui a été fait)
3. Relire ce fichier (CONTEXTE-REFACTORING.md)
4. Consulter le code existant : BidjicTask.freemarkerize()

Si vous reprenez dans 1 mois

1. Lire doc/BidjicDirectives.md (comprendre les directives)
2. Lire doc/Refactoring.md sections 1-2 (problème + plan)
3. Lire doc/Phase1-Inventaire-Complete.md (travail fait)
4. Examiner BidjicPreprocessorTest.java (tests préparés)

📞 Questions Fréquentes

Q: Les tests sont-ils utilisables maintenant ?

R: Non, ils sont commentés car BidjicPreprocessor n’existe pas encore. À activer en Phase 2.

Q: Peut-on sauter la Phase 2 et aller direct en Phase 3 ?

R: Non recommandé. Phase 2 = sécurité avec tests. Phase 3 = changement majeur.

Q: Les directives deprecated peuvent-elles être supprimées maintenant ?

R: Non. Les marquer deprecated en Phase 2, supprimer en Phase 3+ après migration utilisateurs.

Q: Le code actuel continue-t-il de fonctionner ?

R: Oui, Phase 1 = documentation uniquement, aucun changement de code.

Q: Combien de temps pour finir le refactoring complet ?

R:

• Phase 2 : 3-5 jours (amélioration immédiate)
• Phase 3 : 5-7 jours (nouvelle syntaxe)
• Phase 4 : 3-5 jours (cleanup)
• Total : 11-17 jours (environ 2-3 semaines)

📝 Notes pour la Prochaine Session

Points d’Attention

• ⚠️ Ordre des règles nested est critique - bien tester
• ⚠️ Performance - benchmarker avant/après avec templates réels
• ⚠️ Compatibilité - aucun breaking change en Phase 2
• ⚠️ Tests - tous doivent passer au vert avant intégration

Quick Wins Possibles

Si peu de temps disponible, faire dans l’ordre :

1. Créer BidjicPreprocessor (1-2 jours) → Amélioration immédiate
2. Activer les tests (0.5 jour) → Sécurité
3. Intégrer dans BidjicTask (0.5 jour) → Déploiement

Les autres tâches (TemplateValidator, doc auto) peuvent attendre.

✅ Checklist de Reprise

Avant de commencer à coder Phase 2 :

• J’ai lu CONTEXTE-REFACTORING.md (ce fichier)
• J’ai consulté doc/Refactoring.md section Phase 2
• Je comprends le problème avec freemarkerize()
• J’ai regardé le code de BidjicPreprocessorTest.java
• J’ai un environnement de dev fonctionnel (Java, Ant)
• Je peux compiler et tester le projet Bidji
• Je suis prêt à créer les classes dans org.bidji.preprocessor

Bon courage pour la suite du refactoring ! 🚀

Contact : Voir doc/Refactoring.md pour toute question ou clarification.