Serena Explore - Navigation Symbolique

Objectif

Explorer le code du projet MyGGV GPS de manière efficace en utilisant la navigation symbolique plutôt que la lecture de fichiers entiers. Économise les tokens et améliore la précision.

Périmètre

Inclus

• Vue d'ensemble des symboles d'un fichier
• Recherche de symboles par nom ou pattern
• Navigation vers les définitions
• Trouver les références d'un symbole
• Comprendre les relations entre symboles

Exclus

• Modification de code → utiliser serena-edit
• Mémoire projet → utiliser serena-memory
• Lecture de fichiers complets → éviter, utiliser les symboles

Pourquoi Serena ?

Avantages vs Read Tool

| Approche | Tokens | Précision | |----------|--------|-----------| | Read fichier entier | ~1000+ tokens | Bruit inutile | | Serena symbole ciblé | ~100-200 tokens | Exactement ce qu'il faut |

Exemple

// MAUVAIS - Lire tout le fichier
Read({ file_path: "/src/hooks/useRouteManager.js" })
// → 500+ lignes, beaucoup de bruit

// BON - Cibler le symbole
mcp__serena__find_symbol({ symbol_name: "useRouteManager" })
// → Juste la fonction et sa signature

Outils Disponibles

1. get_symbols_overview

Vue d'ensemble des symboles d'un fichier :

mcp__serena__get_symbols_overview({
  file_path: "src/hooks/useRouteManager.js"
})
// Retourne : liste des fonctions, constantes, exports

2. find_symbol

Trouver un symbole spécifique :

mcp__serena__find_symbol({
  symbol_name: "useNavigationState"
})
// Retourne : définition, signature, fichier source

3. search_for_pattern

Recherche par pattern regex :

mcp__serena__search_for_pattern({
  pattern: "use.*Map.*",  // Tous les hooks liés à Map
  file_types: ["js", "jsx"]
})

4. get_related_symbols

Trouver les symboles liés (imports, dépendances) :

mcp__serena__get_related_symbols({
  symbol_name: "useMapConfig"
})
// Retourne : blocksGeoJSON, getPolygonCenter, etc.

5. get_symbol_references

Où un symbole est-il utilisé ?

mcp__serena__get_symbol_references({
  symbol_name: "haversineDistance"
})
// Retourne : tous les fichiers qui l'importent/utilisent

Workflow d'Exploration

Comprendre un fichier

1. get_symbols_overview → Liste des symboles
2. find_symbol → Détails d'un symbole intéressant
3. get_related_symbols → Dépendances

Trouver où modifier

1. search_for_pattern → Trouver les candidats
2. get_symbol_references → Voir l'impact
3. find_symbol → Détails précis avant modification

Comprendre un bug

1. find_symbol → Localiser la fonction suspecte
2. get_related_symbols → Voir les dépendances
3. get_symbol_references → Tracer les appels

Structure du Projet MyGGV GPS

Hooks Principaux

src/hooks/
├── useMapConfig.js        → Configuration carte, GeoJSON blocs
├── useRouteManager.js     → Gestion routes, recalcul
├── useNavigationState.js  → Machine d'état navigation
├── useDeviceOrientation.js → Boussole
├── useMapTransitions.js   → Animations flyTo
├── useBlockPolygons.js    → Rendu polygones
├── useAdaptivePitch.js    → Pitch caméra
├── useSymbolLayerInteractions.js → Clicks sur layers
└── useLocations.js        → Fetch Supabase

Composants Clés

src/components/
├── MapMarkers.jsx         → Markers destination
├── RouteLayers.jsx        → Affichage routes
├── NavigationDisplay.jsx  → UI navigation active
├── MapControls/           → Contrôles carte
└── WelcomeModalMobile.jsx → Sélection destination

Utilitaires

src/lib/navigation.js      → Logique routing (OSRM)
src/utils/geoUtils.js      → Calculs géo
src/utils/mapTransitions.js → Transitions carte

Bonnes Pratiques

1. Toujours commencer par get_symbols_overview avant de chercher dans un fichier
2. Utiliser des patterns précis pour search_for_pattern
3. Éviter Read pour les gros fichiers - préférer la navigation symbolique
4. Vérifier les références avant de modifier un symbole public

Anti-Patterns

❌ Ne pas faire :

// Lire un fichier entier pour trouver une fonction
Read({ file_path: "src/lib/navigation.js" })  // 1248 lignes !

✅ Faire :

// Cibler directement
mcp__serena__find_symbol({ symbol_name: "createRoute" })