# Cas d'usage et recommandations

# Introduction

Ce document présente différents cas d'usage concrets de mgrep et les meilleures configurations pour chacun.

# Cas d'usage 1 : Exploration de codebase inconnu

# Contexte

Vous rejoignez un nouveau projet et devez comprendre comment certaines fonctionnalités sont implémentées.

# Exemples de requêtes

# Trouver comment l'auth est gérée
python sgrep.py "user authentication"

# Comprendre le système de permissions
python sgrep.py "check user permissions"

# Trouver la gestion des emails
python sgrep.py "send email notification"

# Localiser la config de la base de données
python sgrep.py "database connection setup"

# Configuration recommandée

# .env
EMBEDDING_MODEL=jinaai/jina-embeddings-v2-base-code

# Chunking
MAX_CHUNK_LINES=20
OVERLAP=0  # Pas besoin d'overlap pour exploration

# Recherche
python sgrep.py "query" -k 10  # Plus de résultats pour explorer

Pourquoi :

✅ Jina Code comprend bien les concepts du code
✅ k=10 vous donne une vue large
✅ Pas d'overlap = index plus rapide à créer

# Workflow typique

# 1. Indexer le projet
python recreate_index.py
python watcher.py /path/to/project

# 2. Explorer par concepts
python sgrep.py "API endpoints" -k 10
python sgrep.py "data validation" -k 10
python sgrep.py "error handling" -k 10

# 3. Afficher le code d'un résultat intéressant
python sgrep.py "API endpoints" --show-code

# Cas d'usage 2 : Recherche précise de patterns

# Contexte

Vous cherchez un pattern spécifique (ex: toutes les fonctions qui utilisent un decorator particulier).

# Exemples de requêtes

# Trouver toutes les routes admin
python sgrep.py "admin_required decorator"
python sgrep.py "require_admin_perms"

# Trouver les endpoints JWT protégés
python sgrep.py "jwt_required"

# Localiser les validations de formulaire
python sgrep.py "form validation schema"

# Configuration recommandée

# .env
EMBEDDING_MODEL=all-mpnet-base-v2  # Bon compromis vitesse/qualité

# Chunking
MAX_CHUNK_LINES=15  # Plus précis
OVERLAP=0.25  # Léger overlap pour contexte

# Recherche HYBRIDE (par défaut)
# Combine match exact + sémantique
python sgrep.py "jwt_required" -k 5

Pourquoi :

✅ Recherche hybride trouve les noms exacts
✅ Chunks de 15 lignes = très ciblé
✅ Overlap 25% évite de couper les blocs

# Astuce : Combiner avec grep classique

# 1. mgrep pour trouver les fichiers pertinents
python sgrep.py "jwt middleware"
# → trouve : app.py, auth.py

# 2. grep classique pour tous les usages
grep -n "jwt_required" app.py auth.py

# Cas d'usage 3 : Refactoring guidé

# Contexte

Vous devez refactoriser du code et voulez trouver tous les endroits impactés.

# Exemples de requêtes

# Trouver tous les usages d'une ancienne API
python sgrep.py "old_authentication_method"

# Localiser le code qui doit migrer
python sgrep.py "legacy database connection"

# Identifier les patterns à remplacer
python sgrep.py "manual password hashing"

# Configuration recommandée

# .env
EMBEDDING_MODEL=jinaai/jina-embeddings-v2-base-code

# Chunking
MAX_CHUNK_LINES=20
OVERLAP=0.5  # 50% overlap crucial pour refactoring

# Recherche
python sgrep.py "query" -k 20  # Voir tous les usages

Pourquoi :

✅ Overlap 50% assure qu'on rate rien
✅ k=20 pour voir TOUS les endroits
✅ Jina Code comprend les variations de nommage

# Workflow de refactoring

# 1. Identifier tous les usages
python sgrep.py "old_method" -k 20 > usages.txt

# 2. Pour chaque résultat, voir le contexte
python sgrep.py "old_method" --show-code

# 3. Vérifier qu'on a tout trouvé
grep -r "old_method" . | wc -l  # Comparer avec mgrep

# Cas d'usage 4 : Code review

# Contexte

Vous reviewez une PR et voulez comprendre comment le nouveau code s'intègre.

# Exemples de requêtes

# Voir si la feature existe déjà
python sgrep.py "email validation logic"

# Vérifier les patterns similaires dans la codebase
python sgrep.py "API rate limiting"

# Trouver les tests existants pour inspiration
python sgrep.py "test user authentication"

# Configuration recommandée

# .env
EMBEDDING_MODEL=all-mpnet-base-v2  # Rapide pour review

# Chunking
MAX_CHUNK_LINES=20
OVERLAP=0

# Recherche
python sgrep.py "query" -k 5

Pourquoi :

✅ MPNet rapide, résultats en <100ms
✅ Pas d'overlap = réponse instantanée
✅ k=5 suffit pour voir si ça existe

# Workflow de code review

# 1. Indexer le projet SI pas déjà fait
# (watcher.py tourne en background)

# 2. PR ajoute une fonction send_notification()
# Vérifier si pattern similaire existe
python sgrep.py "send notification email"

# 3. PR ajoute validation de données
# Voir comment c'est fait ailleurs
python sgrep.py "validate request data"

# 4. Commenter la PR avec les patterns existants

# Cas d'usage 5 : Documentation vivante

# Contexte

Créer une "carte" du code pour l'onboarding des nouveaux développeurs.

# Exemples

# Générer une liste des endpoints
python sgrep.py "route handler" -k 30 | tee endpoints.txt

# Lister les services disponibles
python sgrep.py "service class" -k 20 | tee services.txt

# Trouver les utilitaires
python sgrep.py "utility function" -k 15 | tee utils.txt

# Script d'onboarding

#!/bin/bash
# onboarding.sh - Génère une carte du projet

echo "=== API Endpoints ===" > project_map.md
python sgrep.py "API route" -k 20 >> project_map.md

echo "\n=== Services ===" >> project_map.md
python sgrep.py "service class" -k 20 >> project_map.md

echo "\n=== Database Models ===" >> project_map.md
python sgrep.py "database model" -k 20 >> project_map.md

echo "\n=== Authentication ===" >> project_map.md
python sgrep.py "authentication flow" -k 10 >> project_map.md

echo "Carte du projet générée : project_map.md"

# Cas d'usage 6 : Debugging

# Contexte

Un bug en production, vous devez vite trouver le code responsable.

# Exemples de requêtes

# Error : "JWT token expired"
python sgrep.py "JWT token expiration" --show-code

# Error : "Database connection lost"
python sgrep.py "database connection retry logic"

# Error : "User not found"
python sgrep.py "user lookup by ID"

# Configuration pour debug rapide

# .env
EMBEDDING_MODEL=all-mpnet-base-v2  # Le plus rapide

# Recherche avec contexte
python sgrep.py "error message" --show-code -k 3

Workflow debug :

# 1. Message d'erreur dans les logs
ERROR: "Invalid JWT signature"

# 2. Recherche rapide
python sgrep.py "JWT signature validation" --show-code

# 3. Identifier le fichier et la ligne
# Résultat : auth.py:45-60

# 4. Ouvrir dans l'éditeur
code auth.py:45

# Cas d'usage 7 : Apprentissage d'un framework

# Contexte

Vous apprenez Flask/Django/Express et voulez voir des exemples réels.

# Exemples de requêtes

# Comment faire des migrations ?
python sgrep.py "database migration script"

# Comment gérer les sessions ?
python sgrep.py "session management"

# Comment faire des tests ?
python sgrep.py "unit test example"

# Comment structurer les routes ?
python sgrep.py "blueprint registration"

# Configuration learning-friendly

# .env
EMBEDDING_MODEL=jinaai/jina-embeddings-v2-base-code

# Chunking
MAX_CHUNK_LINES=25  # Un peu plus de contexte

# Recherche avec code affiché
python sgrep.py "query" --show-code -k 5

# Configurations par taille de projet

# Petit projet (<5k lignes)

# Indexation ultra-rapide
EMBEDDING_MODEL=all-mpnet-base-v2
MAX_CHUNK_LINES=15
OVERLAP=0.5

# Indexation : ~30 secondes
# Recherche : <50ms
# Index : ~10 MB

# Projet moyen (5k-50k lignes)

# Équilibre optimal
EMBEDDING_MODEL=jinaai/jina-embeddings-v2-base-code
MAX_CHUNK_LINES=20
OVERLAP=0.25

# Indexation : ~5 minutes
# Recherche : <100ms
# Index : ~100 MB

# Gros projet (50k-200k lignes)

# Optimisé performance
EMBEDDING_MODEL=all-mpnet-base-v2
MAX_CHUNK_LINES=30
OVERLAP=0

# Indexation : ~20 minutes
# Recherche : <200ms
# Index : ~500 MB

# Monorepo (>200k lignes)

# Stratégie spéciale
EMBEDDING_MODEL=all-MiniLM-L6-v2
MAX_CHUNK_LINES=50
OVERLAP=0

# Indexer par sous-projet
python watcher.py ./api &
python watcher.py ./frontend &
python watcher.py ./services &

# Ou filtrer certains dossiers
# (modifier watcher.py pour exclure vendor/, generated/)

# Intégration dans le workflow

# CI/CD : Maintenir l'index à jour

# .github/workflows/index-code.yml
name: Update Code Index

on:
  push:
    branches: [main]
  pull_request:

jobs:
  index:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2

      - name: Setup Python
        uses: actions/setup-python@v2

      - name: Install dependencies
        run: pip install -r requirements.txt

      - name: Start Elasticsearch
        run: docker run -d -p 9200:9200 elasticsearch:8.15.1

      - name: Index codebase
        run: |
          python recreate_index.py
          python watcher.py . --once  # Mode one-shot

# Pre-commit hook : Vérifier avant commit

# .git/hooks/pre-commit
#!/bin/bash

# Réindexer les fichiers modifiés
git diff --cached --name-only | while read file; do
    if [[ $file == *.py ]] || [[ $file == *.js ]]; then
        echo "Re-indexing $file..."
        # Trigger re-index (nécessite watcher running)
    fi
done

# VSCode extension (futur)

// Commande : "mgrep: Search in codebase"
// → Ouvre panneau avec résultats
// → Clic pour naviguer vers le code

# Métriques et monitoring

# Suivre la qualité des résultats

# Créer un fichier de queries de test
cat > test_queries.txt <<EOF
user authentication
database connection
send email
validate form data
JWT middleware
EOF

# Tester et logger les résultats
while read query; do
    echo "Query: $query"
    python sgrep.py "$query" -k 5 | tee -a results.log
done < test_queries.txt

# Analyser :
# - Top 1 pertinent ? → Precision@1
# - Top 5 pertinent ? → Precision@5

# Comparer les configurations

# Test 1 : CodeBERT
EMBEDDING_MODEL=microsoft/codebert-base python sgrep.py "query" > results_codebert.txt

# Test 2 : Jina
EMBEDDING_MODEL=jinaai/jina-embeddings-v2-base-code python sgrep.py "query" > results_jina.txt

# Comparer manuellement quelle config donne de meilleurs résultats

# Résumé des recommandations par usage

Usage	Modèle	Chunks	Overlap	k	Pourquoi
Exploration	Jina Code	20	0%	10	Vue large, bonne qualité
Recherche précise	MPNet	15	25%	5	Équilibre rapidité/précision
Refactoring	Jina Code	20	50%	20	Rien ne doit être raté
Code review	MPNet	20	0%	5	Rapide, résultats immédiats
Debug	MPNet	20	0%	3	Le plus rapide possible
Learning	Jina Code	25	0%	5	Bon contexte, bonne qualité

# Prochaines étapes

✅ Identifier votre cas d'usage principal
→ Appliquer la configuration recommandée
→ Tester sur quelques queries
→ Ajuster selon vos besoins spécifiques