📋 Guide de contribution

Merci d'envisager de contribuer à BlocMail & BlocNumEtSMS !

---

Avant de commencer

1. Lire le README.md
2. Consulter STATUS.md pour voir ce qui est en cours
3. Vérifier les Issues GitHub ouvertes
4. Pour les grosses fonctionnalités : discuter en issue avant de coder

---

Conventions de code

Style TypeScript

// ✅ Bon
const analyzeEmail = async (headers: string): Promise<AnalysisResult> => { ... };

// ❌ Éviter
const analyzeEmail = async (headers) => { ... };

Élément	Convention	Exemple
Composants React	PascalCase	EmailHeaderAnalyzer.tsx
Hooks	camelCase + use	useSpamAnalysis.ts
Types/Interfaces	PascalCase	SpamAnalysisResult
Fichiers utilitaires	kebab-case	extract-spam-patterns.cjs
Variables	camelCase	emailContent
Colonnes DB	snake_case	email_content

Classes CSS

// Toujours utiliser cn() de @/lib/utils
import { cn } from '@/lib/utils';
className={cn("base", condition && "conditional")}

---

Conventions de branches

feature/{description}     # Nouvelle fonctionnalité
bugfix/{description}      # Correction de bug
hotfix/{description}      # Correction urgente production
docs/{description}        # Documentation uniquement
refactor/{description}    # Refactoring sans changement fonctionnel

Exemples :

• feature/stripe-integration
• bugfix/arcep-cache-ttl
• docs/update-api-reference

---

Conventions de commit

Format Conventional Commits :

<type>(<scope>): <description courte>

[body optionnel]

Types : feat, fix, docs, style, refactor, test, chore

feat(analyzer): add batch email analysis mode
fix(arcep): handle malformed phone number format
docs(api): update SSE streaming examples

Règles :

• Verbe à l'impératif présent
• Pas de majuscule sur la première lettre de la description
• Pas de point final
• Limite 72 caractères pour le titre

---

Processus de Pull Request

1. Créer une branche depuis main
2. Développer la contribution
3. npm run dev — vérifier que tout fonctionne
4. npm run build — vérifier que le build passe
5. npm run lint — zéro warning
6. Créer la PR vers main

Template PR

## Résumé
Description de ce que fait cette PR.

## Changements
- [ ] Feature X implémentée
- [ ] Bug Y corrigé

## Comment tester
1. Lancer `npm run dev`
2. Aller sur `/analyzer`
3. Coller des headers email
4. Vérifier que...

## Screenshots (si applicable)

---

Exigences de tests (Q2 2026)

• Tests unitaires Vitest pour les fonctions pures
• Cibles prioritaires : credits.ts, scoring hybride, normalisation numéros
• Tests Edge Functions avec Deno.test
• Tests E2E Playwright pour les flux critiques

npm run test       # Tests unitaires
npm run test:e2e   # Tests E2E

---

Ajouter un pattern spam

1. Identifier le type et écrire la structure JSON
2. Tester manuellement avec des emails réels
3. Valider l'absence de faux positifs
4. Ajouter dans le fichier source approprié (spam_patterns.json ou source dédiée)
5. Régénérer : node scripts/extract-spam-patterns.cjs --source=all
6. Créer une PR documentée

---

Ne pas faire

• ❌ Modifier src/components/ui/ (composants shadcn auto-générés)
• ❌ Modifier src/integrations/supabase/types.ts (auto-généré)
• ❌ Committer .env ou des clés API
• ❌ Ajouter des console.log en production
• ❌ Utiliser any TypeScript sans justification

---

Contact

Pour toute question sur la contribution : contact.seb205@gmail.com