ISNAD — Conventions de nommage (E11-T3)

Statut : source de vérité officielle pour tout nouveau nom introduit dans le repository — dossier, fichier, module, test, script, migration, branche, commit, document. Ne s'applique pas rétroactivement : aucun fichier existant n'est renommé par ce document (voir §45 et la matrice e11-naming-anomalies.md pour les écarts déjà identifiés).

Construit à partir de l'inventaire réel (E11-T1) et cohérent avec l'architecture cible (E11-T2, règles de dépendance). Toute contradiction trouvée avec T2 est documentée en §21, jamais corrigée silencieusement.

---

1. Dossiers#

Convention par défaut : kebab-case/.

narrator-identity/
book-workspace/
reading-settings/
commentary-alignment/
tradition-graph/

Éviter : NarratorIdentity/, narrator_identity/, Narrator_Identity/, narratorIdentity/.

Exceptions légitimes (documentées, jamais « corrigées ») :

---

2. Composants React#

Convention : PascalCase.tsx, un composant principal exporté par fichier.

NarratorCard.tsx
HadithDetails.tsx
BookNavigation.tsx
ReadingSettingsPanel.tsx
FathAlBariWorkspace.tsx

Éviter : book-navigation.tsx, narrator_card.tsx, Hadithdetails.tsx, component1.tsx.

Les petits composants internes non exportés peuvent rester dans le même fichier que le composant principal si cela améliore la lisibilité (déjà la pratique dans src/features/openiti/components/OpenitiTextRenderer.tsx, par exemple).

Vérifié conforme sur l'existant : les 108 fichiers .tsx de src/components/ respectent déjà 100 % PascalCase (0 anomalie détectée).

---

3. Hooks React#

Convention : useSomething.ts, camelCase avec préfixe use.

useScrollSpy.ts
useReadingPreferences.ts
useLibraryFilters.ts

Le préfixe use n'est légitime que si le fichier respecte réellement les règles d'un hook React (appelle useState/useEffect/un autre hook, régi par les règles des hooks). Ne jamais nommer une simple fonction utilitaire useXxx si elle n'est pas un hook.

Écart connu sur l'existant (documenté, non corrigé ici) : src/features/reading/use-scroll-spy.ts exporte un vrai hook React (useScrollSpy, utilise useEffect/useState) mais son fichier est nommé en kebab-case au lieu de useScrollSpy.ts — voir la matrice d'anomalies, sévérité MEDIUM.

---

4. Modules TypeScript non-React#

Deux sous-conventions coexistent légitimement, déterminées par les données réelles du repository (comptage exhaustif ci-dessous) — ce n'est pas une incohérence à corriger, c'est une distinction fonctionnelle réelle entre deux styles de module :

Règle formalisée :

Le fichier exporte principalement UNE classe / UN service / UNE entité
nommée en PascalCase, et cette classe EST la raison d'être du fichier ?
  → PascalCase.ts (nom du fichier = nom de l'export principal)
  → C'EST la convention établie de domain/ et infrastructure/ (103 fichiers
    existants), pas une exception à corriger.

Sinon (fonctions, primitives, modules de lecture, orchestration légère) ?
  → kebab-case.ts
  → C'EST la convention établie de server/, lib/, components/, app/
    (107 fichiers existants).

Exemples de nouveaux fichiers corrects sous cette règle :

domain/tradition-variant/TraditionClassification.ts     (classe → PascalCase)
server/commentary/commentary-read.ts                     (déjà conforme, lecture pure)
lib/library-catalog.ts                                    (déjà conforme, fonctions)

Ne pas convertir arbitrairement les fichiers React .tsx PascalCase existants en kebab-case (règle §5 de la mission — sans ambiguïté ici, .tsx reste toujours PascalCase quel que soit le contenu).

---

5. Domain entities / value objects#

Le type/classe exporté est en PascalCase :

TraditionCandidate
TraditionEvidence
NarratorIdentity
HadithAggregate
DocumentaryWitness

Le fichier suit la règle §4 : s'il porte principalement cette entité, il est nommé TraditionCandidate.ts (déjà la convention dominante de domain/, voir §4) — pas tradition-candidate.ts, sauf si une équipe future décide explicitement d'inverser la convention pour tout domain/ (changement majeur, hors périmètre T3).

---

6. Types / interfaces#

Préférer des noms métier explicites :

NarratorIdentity
TraditionCandidate
CommentaryPassage
BookNavigationNode

Éviter : Data, Result, Item, Obj, Payload2, TmpType, Thing.

Vérifié sur l'existant : aucune occurrence de ces noms génériques trouvée dans src/domain/, src/server/, src/lib/ (grep ciblé, 0 résultat) — bonne discipline déjà en place, à maintenir.

Dto uniquement lorsqu'il s'agit réellement d'un contrat de transport (sérialisation entre couches, ex. réponse d'API publique) :

CommentaryWorkDto
NarratorSearchResultDto

Ne pas suffixer systématiquement par Dto — la majorité des interfaces actuelles (FathKitabSummary, OpenitiP0WorkAvailability, LibraryBook) n'en ont pas besoin car elles ne franchissent qu'une seule frontière server→client simple, déjà nommées par leur rôle métier.

---

7. Services#

Nommer par responsabilité :

tradition-candidate-service.ts
commentary-read.ts
narrator-search.ts

Éviter les noms génériques : service.ts, services.ts, manager.ts, helper.ts, utils.ts — sauf pour une primitive réellement générique et bien définie (aucune occurrence de ces noms interdits trouvée dans le repo actuel — bonne base à préserver).

---

8. Repositories / ports (domain/)#

narrator-repository.ts   → NarratorRepository (interface)
hadith-repository.ts     → HadithRepository (interface)
tradition-repository.ts  → TraditionRepository (interface)

Écart avec l'existant à documenter (pas une erreur — cohérent avec §4) : les 9 fichiers actuels de src/domain/repositories/ sont déjà nommés en PascalCase (HadithAggregateWriter.ts, NarratorRepository.ts, RijalKnowledgeWriter.ts, etc.), conformément à la règle §4 (le fichier exporte une interface PascalCase). La forme narrator-repository.ts proposée par la mission comme exemple générique n'est pas la convention réellement en place pour les ports du domaine — celle-ci reste NarratorRepository.ts. Documenté ici pour éviter toute confusion future, pas de changement recommandé (les 9 fichiers existants restent PascalCase).

9. Adapters / implémentations (infrastructure/)#

SupabaseHadithAggregateWriter.ts
PostgresRijalProvenanceResolver.ts

ou en kebab-case pour les adapters non centrés sur une classe unique (postgres-narrator-repository.ts serait acceptable si le fichier n'exporte pas une classe mais un ensemble de fonctions). La technologie peut apparaître dans le nom d'un adapter d'infrastructure (Supabase*, Postgres*) — elle ne doit jamais apparaître dans une interface domain/ (déjà vérifié conforme : 0 occurrence de Supabase/Postgres dans les noms d'interfaces sous src/domain/).

Convention adapter explicite (uniquement quand le pattern Adapter est réellement présent) :

<technology>-<responsibility>-adapter.ts
openiti-text-adapter.ts
supabase-narrator-adapter.ts

Ne pas ajouter Adapter/-adapter par décoration si la classe n'implémente pas réellement une interface domain/ distincte.

---

10. Server readers / queries (server/)#

<domain>-read.ts

Acceptable lorsque le rôle est clairement une lecture serveur read-only sans port domain/ formel derrière (voir D2, dependency-rules.md).

Déjà conforme dans le repo :

src/server/openiti/corpus-read.ts
src/server/commentary/commentary-read.ts

Si un port domain/repositories/ formel est introduit plus tard pour l'une de ces zones, l'implémentation migre vers infrastructure/ (règle D2) — le fichier server/*-read.ts d'origine peut alors disparaître ou devenir un simple point d'entrée fin.

---

11. API routes (Next.js App Router)#

Respecter strictement la convention du framework :

route.ts

Le chemin du dossier porte toute la sémantique :

src/app/api/corpus/commentary/works/route.ts

Interdit : commentary-api.ts, apiRoute.ts, handler.ts en lieu et place de route.ts dans l'arborescence App Router.

Vérifié conforme : les 20 routes API actuelles utilisent toutes route.ts.

---

12. Routes Next.js (pages, layouts)#

Conserver strictement :

page.tsx
layout.tsx
loading.tsx
error.tsx
not-found.tsx
route.ts

Segments dynamiques : [locale], [workUri], [bookId], [sourceKey], [bookDir], [hadithId], [[...slug]]. Groupes de route : (site).

Aucun renommage hors convention Next.js. 41 page.tsx, 5 layout.tsx, 20 route.ts déjà 100 % conformes (voir T1 §6).

---

13. Tests unitaires#

<source-file>.test.ts
<component>.test.tsx

Colocalisés avec le code testé — déjà la convention à 100 % sur les 51 fichiers *.test.ts/*.test.tsx existants (0 test dans un dossier __tests__/ séparé au niveau src/, à l'exception assumée de scripts/translations/__tests__/ qui suit une convention Node standard distincte et légitime pour les scripts).

14. Tests d'intégration#

*.integration.test.ts

Emplacement : src/tests/integration/ — ce dossier n'existe pas encore (confirmé absent en T1). Convention réservée pour le jour où un véritable test d'intégration cross-module (au-delà d'un test unitaire colocalisé ou d'un script scripts/test-*.mjs) sera introduit. Aucun dossier créé maintenant (§2 de la mission — pas de structure vide par anticipation).

15. Tests end-to-end#

*.e2e.test.ts

Emplacement proposé si adopté plus tard : tests/e2e/. Aucun outil E2E n'est installé aujourd'hui (T1 : ni Playwright ni Cypress trouvés). Convention réservée, aucun framework créé en T3.

16. Tests SQL (supabase/tests/)#

Convention déjà observée et confirmée cohérente sur les 37 fichiers existants (analyse effectuée avant de choisir, comme demandé §19) :

<timestamp>_<domaine_en_snake_case>_test.sql

Exemples réels : 20260827120000_quality_engine_core_test.sql, commentary_foundation_test.sql (sans timestamp pour certains tests plus anciens — accepté tel quel, KEEP AS-IS). Snake_case confirmé comme la bonne convention — c'est déjà celle en place, formalisée ici plutôt que réinventée.

17. Migrations SQL#

Convention impérative, jamais renommée après application :

YYYYMMDDHHMMSS_description_en_snake_case.sql

Exemple réel : 20260908160000_... (186 migrations existantes, toutes conformes). Les migrations historiques restent KEEP AS-IS même si un nom n'est plus idéal — aucune migration appliquée n'est renommée, jamais, pour de l'harmonisation cosmétique.

---

18. Scripts (scripts/)#

Convention retenue : kebab-case.mjs (ou .ts si le runtime évolue).

Décision sur la redondance dossier/préfixe (§21 de la mission) : dans la structure cible définie en T2 (scripts/{audit,import,validation,maintenance,migration}/), le préfixe répétant le rôle du dossier devient redondant. Convention future adoptée :

scripts/audit/tradition-candidates.mjs        (pas audit-tradition-candidates.mjs)
scripts/validation/narrator-resolution.mjs     (pas test-narrator-resolution.mjs)
scripts/migration/fath-corpus-manifest.mjs      (pas build-fath-corpus-manifest.mjs)

Non appliqué maintenant : les 182 scripts existants gardent leur préfixe (test-*, audit-*, build-*) tant que la migration physique scripts/ (M4, voir T2 §21) n'a pas eu lieu — renommer maintenant sans déplacer casserait les références package.json pour un gain nul avant la restructuration réelle. Cette convention s'applique dès aujourd'hui aux nouveaux scripts créés dans un sous-dossier déjà existant (scripts/quality-engine/, scripts/lib/, scripts/translations/) et à tout nouveau script créé à plat (qui garde le préfixe tant qu'il n'a pas de sous-dossier dédié, ex. un nouveau audit-xxx.mjs à la racine de scripts/ avant que M4 ne soit exécuté).

---

19. Documentation Markdown#

kebab-case.md

Exemples : repository-structure.md, dependency-rules.md, naming-conventions.md.

Exceptions : README.md, CHANGELOG.md, CONTRIBUTING.md, LICENSE.md (majuscules, convention universelle GitHub/OSS).

Éviter : FINAL_REPORT.md, NewDoc.md, doc_v2.md, test.md.

Écart connu sur l'existant (documenté, non renommé) : AUDIT-REPORT.md (racine, SCREAMING-KEBAB) et le groupe RIJAL_CANONICAL_REFERENCE_*.md / LIVE_AGENT_*.md / SCIENTIFIC_KNOWLEDGE_LAYER_ROADMAP.md / ISNAD_SCIENTIFIC_PRINCIPLES.md / KNOWLEDGE_MODEL_V1.md / DOMAIN_LAYER_V1.md sous docs//planning/ (SCREAMING_SNAKE_CASE) — voir la matrice d'anomalies pour le détail complet.

19.1 Documents d'epic#

e01-acquisition.md
e02-canonical-models.md
e03-provenance.md
e04-narrator-identity.md
e05-tradition-variant-graph.md
...
e11-repository-hygiene.md

Décision : e01 à e11 (deux chiffres), pas e1/e2 — tri lexical stable garanti au-delà de 9 epics (déjà pertinent : E11 est en cours). Les fichiers existants nommés e2-*, e3-*, e4-*, e5-* (un seul chiffre) ne sont pas renommés en T3 — la convention à deux chiffres s'applique aux nouveaux documents d'epic à partir de maintenant (en pratique, E11 étant déjà à deux chiffres, la transition est déjà amorcée naturellement).

19.2 Audits#

<epic>-<subject>-audit.md

Exemples réels déjà conformes : e11-repository-inventory.md, e11-target-file-placement.md. Éviter les timestamps dans le nom sauf si plusieurs audits chronologiques du même sujet l'exigent réellement (ex. un futur e11-repository-inventory-2027.md si un second audit complet devait être fait un jour).

19.3 Rapports#

<epic>-<milestone>-report.md

Exemple : e11-final-certification-report.md (à créer lors de la clôture d'E11, pas maintenant).

19.4 Archives#

Dans planning/archive/ : conserver le nom historique du contenu archivé (ne jamais renommer massivement un historique — cela détruit son contexte de recherche), en l'enveloppant dans un dossier daté :

planning/archive/2026-08-e4-night-shift/

---

20. JSON#

Convention dépend strictement du rôle :

Éviter pour tout nouveau fichier : SCREAMING_SNAKE.json, audit_candidates_final.json, data2.json.

---

21. YAML / YML#

kebab-case.yml

sauf convention imposée par l'outil : .github/workflows/<workflow-name>.yml (dossier .github/ n'existe pas encore dans ce repo — réservé pour l'introduction future d'une CI, voir T1 risque « absence de CI »).

22. Shell / PowerShell#

kebab-case.sh
kebab-case.ps1

Exemples : verify-production.ps1, prepare-openiti-import.sh.

Écart connu : data-export/export-access.ps1 est déjà conforme (kebab-case). Aucune anomalie shell/PowerShell détectée sur les 3 .sh + 3 .ps1 du repo actuel.

23. CSS#

globals.css imposé par Next.js — inchangé. Pour d'éventuels modules CSS futurs : ComponentName.module.css. Aucun CSS module créé maintenant — le repo n'en a aucun aujourd'hui (1 seul fichier .css, globals.css).

---

24. Constantes#

UPPER_SNAKE_CASE

Uniquement pour des constantes réellement globales et immuables (DEFAULT_PAGE_SIZE, MAX_CANDIDATE_RESULTS) — pas pour toute variable const locale.

25. Enums#

Préférer les unions de types TypeScript quand elles suffisent (c'est déjà l'écrasante majorité du repo — ex. LibraryCategory, PassageKind définis comme unions littérales, pas comme enum). Si un enum réel est strictement nécessaire : PascalCase pour l'enum et ses membres, sans introduire de nouvelle politique enum sans besoin démontré.

26. Fonctions#

camelCase

Verbe explicite recommandé : buildOpenitiNavigation(), findTraditionCandidates(), normalizeArabicText().

27. Variables#

camelCase

Éviter les acronymes cryptiques : préférer narratorId, collectionId, traditionCandidate à nid, cid, tc — sauf boucle locale évidente (i, j dans une boucle for bornée restent acceptables).

28. Booléens#

Préfixes recommandés : is, has, can, should.

isAvailable
hasProvenance
canEdit
shouldRenderNavigation

---

29. Identifiants DB vs code (mapping snake_case → camelCase)#

Ne jamais renommer une colonne DB existante pour des raisons cosmétiques. Dans TypeScript, un mapper doit convertir snake_case (DB) vers camelCase (application/domaine) à la frontière entre la couche de lecture SQL et l'interface publique consommée par le reste de l'application.

Vérifié conforme sur l'exemple le plus récent : src/server/commentary/commentary-read.ts type ses lignes SQL brutes en snake_case (book_dir, bab_number — cohérent avec les colonnes réelles) mais ses interfaces exportées (FathKitabSummary, FathBab) sont intégralement en camelCase (bookDir, babCount, alignedBookTitleAr) — c'est exactement le mapping attendu, à reproduire pour tout nouveau module server//infrastructure/. Ne jamais laisser un type snake_case franchir la frontière vers domain/, features/ ou app/.

---

30. Nommage arabe / translittéré#

Dans les noms de fichiers et symboles TypeScript : utiliser l'anglais technique ou le vocabulaire scientifique translittéré sans caractères spéciaux (pas de diacritiques ā/ṭ/ḥ/ʿ dans un nom de fichier ou un identifiant de code — complique l'outillage et les systèmes de fichiers).

Acceptable dans le code : isnad, tabaqa, rijal, hadith, matn. À éviter dans les noms de fichiers/symboles : ṭabaqa, rijāl, ḥadīth.

Dans l'UI et les données scientifiques affichées à l'utilisateur : la translittération scientifique complète (Ṣaḥīḥ al-Bukhārī, Ibn Ḥajar al-ʿAsqalānī) reste intégralement conservée — cette règle ne concerne que les noms de fichiers et identifiants de code, jamais le contenu scientifique affiché.

---

31. Terminologie française / anglaise#

Le code utilise l'anglais technique. L'UI reste en français/arabe. Le vocabulaire scientifique islamique standardisé est autorisé tel quel dans le code (hadith, isnad, matn, tabaqa, rijal — déjà la pratique constante du repo, ex. src/domain/narrator-identity/tabaqa.ts, src/domain/narrator-identity/isnadMatching.ts).

Éviter tout mélange comme getNarrateur()/buildChapitre().

Vérifié conforme : aucune fonction/variable en français trouvée par échantillonnage dans src/domain/ et src/lib/ — la discipline actuelle est déjà bonne, à maintenir strictement pour tout nouveau code.

---

32. Barrels (index.ts)#

À utiliser avec parcimonie, uniquement pour exposer l'API publique d'un module domain//infrastructure//server/ cohérent. Interdit comme réflexe systématique dans chaque dossier.

État actuel : 12 barrels dans tout src/ — tous à des frontières de module réelles (domain/entities/, domain/narrator-identity/, domain/repositories/, domain/services/, domain/tradition-variant/, domain/types/, domain/knowledge-acquisition/, infrastructure/repositories/, lib/hadithrank/, server/live-agent/ et ses deux sous-modules). Aucun barrel superflu détecté — bon usage déjà en place, à reproduire pour toute nouvelle feature (un seul index.ts par module cohérent, jamais un par sous-dossier interne).

Éviter les cycles d'import cachés : un barrel ne doit jamais réexporter un module qui importe lui-même (directement ou transitivement) ce même barrel.

---

33. Branches Git#

feature/<scope>
fix/<scope>
refactor/<scope>
docs/<scope>
chore/<scope>
test/<scope>

Exemples : feature/e5-tradition-graph, refactor/e11-source-tree, docs/e11-architecture, fix/openiti-reading.

Éviter : dev2, final, testbranch, new-feature, claude-fix.

Constat sur l'existant (T1 §14) : 100 branches distantes, préfixes globalement disciplinés (feature/, audit/, data/, night/, remediation/, search/, ui/, integration/, codex/, chore/, build/, wave-0/, recovery-gate/, epic/) — aucune branche existante ne viole grossièrement cette convention (pas de dev2, final, testbranch trouvés). Les préfixes audit/, data/, night/, search/, ui/, codex/, wave-0/, recovery-gate/, integration/ restent acceptés comme variantes historiques légitimes de feature/ — non renommés, la convention ci-dessus s'applique aux nouvelles branches.

---

34. Commits — Conventional Commits#

feat(scope): ...
fix(scope): ...
refactor(scope): ...
docs(scope): ...
test(scope): ...
chore(scope): ...
build(scope): ...
ci(scope): ...

Exemples réels déjà conformes : refactor(reading): move shared workspace components, docs(e11): define naming conventions, chore(repo): untrack generated TypeScript build info.

Scopes recommandés (liste indicative, non rigide — ne pas bloquer un commit pour un scope absent de cette liste) :

repo, corpus, reading, openiti, commentary, hadith, narrator, tradition,
provenance, admin, db, docs, e11

---

35. Tags Git#

Aucun tag n'existe encore dans le repository (confirmé T1). Convention proposée pour l'avenir, aucun tag créé en T3 :

v0.x.y                    (releases produit)
beta-design-2026-09        (jalons historiques nommés, si besoin)

---

36. Variables d'environnement#

UPPER_SNAKE_CASE

Exemples réels : DATABASE_URL, NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY. Aucune variable actuelle renommée sans audit d'usage complet (hors périmètre T3 — un renommage de variable d'environnement casse le déploiement Vercel si mal coordonné).

---

37. Fichiers générés#

Ne doivent jamais suivre une convention métier — ils sont GENERATED / UNTRACKED / GITIGNORED, traité en détail dans une future micro-tâche E11 (T4, non exécutée ici). Exemples déjà identifiés en T1 :

tsconfig.tsbuildinfo   (actuellement tracké par erreur — voir T2 §11)
.next/
coverage/ (n'existe pas encore, aucun outil de couverture configuré)

---

38. Règle de renommage futur#

Ne renommer un fichier existant que si les trois conditions sont réunies simultanément :

1. le nom actuel viole une convention de ce document
   ET
2. le renommage améliore réellement la clarté (pas juste l'esthétique)
   ET
3. toutes les références peuvent être mises à jour en sécurité
   (imports, package.json, documentation, liens)

Ne jamais renommer pour la seule perfection esthétique.

---

39. Récapitulatif express (pour un développeur pressé)#

---

Document produit par E11-T3. Ne renomme rien. Sert de référence pour toute création future de fichier, dossier, symbole ou identifiant Git.