Doctrine

Conventions de code

Conventions de code

Dernière mise à jour : 2026-05-10

Source de vérité : CONTRIBUTING.md. Cette page reformule les règles structurantes.

Règles d'or backend

1. Logger central uniquement

Vérifier :

grep -rn "console\." src/ --include="*.ts" | grep -v src/lib/logger.ts | grep -v src/config.ts
# → doit retourner zéro résultat

2. Variables d'env centralisées

Quand on ajoute une var, 3 fichiers en parallèle :

  1. src/config.ts
  2. .env.example (commentaire explicite)
  3. unraid/boardgame-referee.xml

Et si la var change un comportement structurel, mettre à jour ARCHITECTURE.md.

3. Helper envBool() pour les booléens

4. Repository pattern (Phase 2)

5. Services découpés (Phase 3) — barrel imports

6. Stages d'ingestion : signature standard

async function runStageX(
  game: Game,
  ...,
  push: EventPusher
): Promise<...>

7. Aucun cache global dans services/rag/retrieve/

8. Code partagé — ne pas réinventer

Avant d'écrire un utilitaire, vérifier qu'il n'existe pas dans :

Règles d'or frontend

1. Pas de scoped CSS qui contredit Tailwind

2. Type-check via --build (pas --noEmit)

3. Regex avec flag u pour Unicode

4. Composants async pour les modales lourdes

const CardZoomModal = defineAsyncComponent(() => import('./components/CardZoomModal.vue'))

CardZoomModal + DeckImportModal : ~50 KB gzip retirés du bundle initial PlayView.

Conventions de nommage

Convention de commits

Convention courte façon Conventional Commits :

type(scope): description courte

Optional body

Exemples actuels :

Types courants : feat, fix, refactor, perf, chore, docs, test, style, security.

Linter / formatter

Pas de eslint/prettier formel actuellement. Convention manuelle :

Si tu veux ajouter eslint+prettier : config standard Vue + TS, no-config-thrasher.

Tests

Tests

Dernière mise à jour : 2026-05-10

Deux types de tests, complémentaires :

  1. Vitest unitaires : déterministes, détectent les régressions silencieuses
  2. Banc d'éval RAG : qualité subjective de l'oracle (judge Haiku)

Vitest unitaires

Périmètre

Toute fonction critique non triviale ajoutée à src/lib/, src/services/, frontend/src/composables/ ou frontend/src/stores/ doit avoir un test unitaire dans le même dossier sous la forme *.test.ts.

Les routes et les vues n'en ont pas besoin (pure orchestration), mais leurs services sous-jacents si.

Garde-fous prioritaires

Mock le strict minimum

// OK — mock config + repos quand on touche fs / DB
vi.mock('../config.js', () => ({ config: { LOG_LEVEL: 'debug', ... } }))
vi.mock('../repositories/games.repo.js')

// PAS OK — pas de mock fs/path
// → utiliser os.tmpdir() + randomUUID() pour un vrai dossier isolé

Plus simple, moins fragile.

Lancer

# Backend
npm test              # Run complet
npm run test:watch    # Watch

# Frontend
cd frontend && npm test

CI

npm test doit passer en CI (job test dans .gitea/workflows/build.yml). Si un test échoue, on corrige le code (ou le test si l'attendu était faux). On ne skip pas.

Banc d'éval RAG

Différence avec les tests unitaires

Vitest unit Banc RAG
But Régressions silencieuses dans la mécanique Qualité subjective de l'oracle
Source Code TS Questions + ground truth
Verdict Déterministe (assert) Subjectif (judge LLM)
Coût Gratuit Quota Claude (Haiku)
Fréquence À chaque commit Manuellement, après gros changements RAG

Localisation

tests/rag/ — séparé de Vitest, lancé avec ses propres scripts.

Commandes

npm run test:rag              # Run complet
npm run test:rag:capture      # Capture les réponses pour archive (snapshot)
npm run test:rag:report       # Rapport markdown
npm run test:rag:html         # HTML interactif
npm run test:rag:html:serve   # Serveur local viewer (port 8888 défaut)

Workflow typique

  1. Faire un changement RAG significatif (HyDE, RRF, prompt, retrieval params…)
  2. npm run test:rag → run les questions test
  3. npm run test:rag:html → générer rapport HTML interactif
  4. npm run test:rag:html:serve → ouvrir http://localhost:8888 et comparer les réponses
  5. Décider : régression acceptable / fix nécessaire

Alimenter le banc

Tests frontend

Vitest + Vue Test Utils. Localisé sous frontend/src/**/*.test.ts.

Couvre :

Pas de tests E2E Playwright actuellement. Pourrait être ajouté plus tard pour les flows critiques (login → ingest jeu test → poser question → vérifier réponse).

Coverage

Pas de seuil enforcé. Vitest peut générer un rapport --coverage :

npm test -- --coverage

Mais pas de fail-on-low-coverage. Convention : si tu touches une fonction critique, le test existe.

Pièges connus

Mock partiel d'un module ESM

Tests qui dépendent de la timezone

Tests qui dépendent de fichiers réels

Tests qui appellent vraiment l'API Claude