Analyser du code via LSP pour naviguer et refactorer

name: lsp-code-analysis description: Analyse sémantique du code via LSP. Naviguez dans le code (définitions, références, implémentations), recherchez des symboles, prévisualisez les refactorisations et obtenez des contours de fichiers. À utiliser pour explorer des bases de code inconnues ou effectuer des refactorisations sûres. license: LICENSE

tags: [lsp-code-analysis, search, citation-management] ---------------- | ---------------- | ----------------------------------------------- | | Trouver la Définition | grep, read | definition | | Trouver les Usages | grep -r | reference | | Comprendre le Fichier | read | outline | | Voir la Doc/Types | read | doc | | Refactoriser | sed | Voir Guide de Refactorisation |

Commands

Toutes les commandes supportent -h ou --help.

Localiser les Symboles

La plupart des commandes utilisent une syntaxe de localisation unifiée via les options --scope et --find.

Arguments : <file_path>

Options :

--scope : Limiter la recherche au corps d'un symbole ou à une plage de lignes.
--find : Motif textuel à trouver dans la portée.

Formats de Portée :

<line> : Numéro de ligne unique (ex. 42).
<start>,<end> : Plage de lignes (ex. 10,20). Utiliser 0 pour la fin pour signifier jusqu'à la fin du fichier (ex. 10,0).
<symbol_path> : Chemin du symbole avec des points (ex. MyClass.my_method).

Motif de Recherche (--find) :

L'option --find affine la cible à un motif textuel au sein de la portée sélectionnée :

La portée est déterminée par --scope (ligne/plage/symbole). Si aucun --scope n'est fourni, le fichier entier est la portée.
La correspondance de motif est insensible aux espaces : les différences d'espaces, de tabulations et de retours à la ligne sont ignorées.
Vous POUVEZ inclure le marqueur de curseur <|> à l'intérieur du motif pour spécifier la position exacte d'intérêt dans la correspondance (par exemple, sur un nom de variable, un mot-clé ou un opérateur).
Si --find est omis, la commande utilise le début de la portée (ou une valeur par défaut spécifique à l'outil) comme cible de navigation.

Marqueur de Curseur (<|>) :

Le marqueur <|> indique la position exacte pour la résolution de symbole. Il représente le caractère immédiatement à sa droite. Utilisez-le dans le motif de recherche pour pointer vers un élément spécifique (ex. user.<|>name pour cibler la propriété name).

Exemples :

lsp doc foo.py --find "self.<|>" - Trouver self. dans le fichier entier, positionner au caractère après le point (généralement pour la complétion ou l'accès aux membres)
lsp doc foo.py --scope 42 --find "return <|>result" - Trouver return result à la ligne 42, positionner à r de result
lsp doc foo.py --scope 10,20 --find "if <|>condition" - Trouver if condition dans les lignes 10-20, positionner à c de condition
lsp doc foo.py --scope MyClass.my_method --find "self.<|>" - Trouver self. dans MyClass.my_method, positionner après le point
lsp doc foo.py --scope MyClass - Cibler directement le symbole MyClass

Guideline pour Portée vs Recherche :

Utiliser --scope <symbol_path> (ex. --scope MyClass, --scope MyClass.my_method) pour cibler les classes, fonctions ou méthodes. C'est la manière la plus robuste et préférée pour cibler un symbole.
Utiliser --find (souvent combiné avec --scope) pour cibler des variables ou des positions spécifiques. Utiliser ceci quand la cible n'est pas un symbole nommé de manière unique ou quand vous avez besoin de pointer une utilisation spécifique dans un bloc de code.

Les agents PEUVENT utiliser lsp locate <file_path> --scope <scope> --find <find> pour vérifier que la cible existe dans le fichier et voir son contexte avant d'exécuter d'autres commandes.

# Vérifier que la localisation existe
lsp locate main.py --scope 42 --find "<|>process_data"

Pagination

Utiliser la pagination pour les grands ensembles de résultats comme reference ou search.

--pagination-id <ID> : (Obligatoire) Identifiant de session unique pour une pagination cohérente.
--max-items <N> : Taille de la page.
--start-index <N> : Décalage (basé sur 0).

Exemple :

# Page 1
lsp search "User" --max-items 20 --pagination-id "task_123"

# Page 2
lsp search "User" --max-items 20 --start-index 20 --pagination-id "task_123"

Guideline : Utiliser la pagination avec un ID unique pour les symboles courants afin de récupérer les résultats par chunks gérables. Incrémenter --start-index en utilisant le même ID pour naviguer.

Outline : Structure du Fichier

Obtenir la structure hiérarchique des symboles sans lire l'implémentation.

# Obtenir les symboles principaux (classes, fonctions, méthodes)
lsp outline <file_path>

# Obtenir tous les symboles incluant les variables et paramètres
lsp outline <file_path> --all

Les agents DEVRAIENT utiliser outline avant de lire les fichiers pour éviter une consommation inutile de contexte.

Definition : Naviguer vers la Source

Naviguer vers l'endroit où les symboles sont définis.

# Sauter à la définition de User.get_id
lsp definition models.py --scope User.get_id

# Trouver d'où provient une variable importée
lsp definition main.py --scope 42 --find "<|>config"

# Trouver la déclaration (ex. fichiers d'en-tête, déclarations d'interface)
lsp definition models.py --scope 25 --mode declaration --find "<|>provider"

# Trouver la définition de classe du type d'une variable
lsp definition models.py --scope 30 --find "<|>user" --mode type_definition

Reference : Trouver Tous les Usages

Trouver où les symboles sont utilisés ou implémentés.

# Trouver tous les endroits où logger est référencé
lsp reference main.py --scope MyClass.run --find "<|>logger"

# Trouver toutes les implémentations concrètes d'une interface/classe abstraite
lsp reference api.py --scope "IDataProvider" --mode implementations

# Obtenir plus de contexte autour de chaque référence
lsp reference app.py --scope 10 --find "<|>my_var" --context-lines 5

# Limiter les résultats pour les grandes bases de code
lsp reference utils.py --find "<|>helper" --max-items 50 --start-index 0

Doc : Obtenir la Documentation

Obtenir la documentation et les informations de type sans naviguer vers la source.

# Obtenir la docstring et les informations de type pour le symbole à la ligne 42
lsp doc main.py --scope 42

# Obtenir la documentation API pour la fonction process_data
lsp doc models.py --scope process_data

Les agents DEVRAIENT préférer doc à read quand seule la documentation ou les informations de type sont nécessaires.

Search : Recherche Globale de Symboles

Rechercher des symboles dans l'espace de travail quand la localisation est inconnue.

# Rechercher par nom (par défaut dans le répertoire courant)
lsp search "MyClassName"

# Rechercher dans un projet spécifique
lsp search "UserModel" --project /path/to/project

# Filtrer par type de symbole (peut être spécifié plusieurs fois)
lsp search "init" --kinds function --kinds method

# Limiter et paginer les résultats pour les grandes bases de code
lsp search "Config" --max-items 10
lsp search "User" --max-items 20 --start-index 0

Les agents DEVRAIENT utiliser --kinds pour filtrer les résultats et réduire le bruit.

Symbol : Obtenir le Code Complet du Symbole

Obtenir le code source complet du symbole contenant une localisation.

# Obtenir le code complet de la fonction/classe à la ligne 15
lsp symbol main.py --scope 15

# Obtenir l'implémentation complète de UserClass
lsp symbol utils.py --scope UserClass

# Obtenir l'implémentation complète de la méthode
lsp symbol models.py --scope User.validate

La réponse inclut : nom du symbole, type (class/function/method), plage et code source complet.

Les agents DEVRAIENT utiliser symbol pour lire des blocs de code ciblés au lieu d'utiliser read sur des fichiers entiers.

Opérations de Refactorisation

Lire Guide de Refactorisation pour renommer, extraire et autres opérations de refactorisation sûre.

Server : Gérer les Serveurs en Arrière-Plan

Le gestionnaire en arrière-plan démarre automatiquement. Le contrôle manuel est OPTIONNEL.

# Lister les serveurs actifs
lsp server list

# Démarrer le serveur pour un projet
lsp server start <path>

# Arrêter le serveur pour un projet
lsp server stop <path>

# Arrêter le gestionnaire en arrière-plan
lsp server shutdown

Bonnes Pratiques

Workflows Généraux

Comprendre du Code Inconnu

La séquence RECOMMANDÉE pour explorer de nouvelles bases de code :

# Étape 1 : Commencer par outline - Obtenir la structure du fichier sans lire l'implémentation
lsp outline <file_path>

# Étape 2 : Inspecter les signatures - Utiliser doc pour comprendre les contrats API
lsp doc <file_path> --scope <symbol_name>

# Étape 3 : Naviguer dans les dépendances - Suivre les chaînes de définition
lsp definition <file_path> --scope <symbol_name>

# Étape 4 : Mapper l'utilisation - Trouver où le code est appelé avec reference
lsp reference <file_path> --scope <symbol_name>

Déboguer un Comportement Inconnu

# Étape 1 : Localiser la définition du symbole dans l'espace de travail
lsp search "<symbol_name>"

# Étape 2 : Vérifier les détails d'implémentation
lsp definition <file_path> --scope <symbol_name>

# Étape 3 : Tracer tous les appelants pour comprendre le contexte d'invocation
lsp reference <file_path> --scope <symbol_name>

Trouver les Implémentations d'Interface

# Étape 1 : Localiser la définition de l'interface
lsp search "IUserService" --kinds interface

# Étape 2 : Trouver toutes les implémentations
lsp reference src/interfaces.py --scope IUserService --mode implementations

Tracer le Flux de Données

# Étape 1 : Trouver où les données sont créées
lsp search UserDTO --kinds class

# Étape 2 : Trouver où elles sont utilisées
lsp reference models.py --scope UserDTO

# Étape 3 : Vérifier les transformations
lsp doc transform.py --scope map_to_dto

Comprendre les Hiérarchies de Types

# Étape 1 : Obtenir le contour de la classe
lsp outline models.py

# Étape 2 : Trouver les sous-classes (références à la base)
lsp reference models.py --scope BaseModel

# Étape 3 : Vérifier les définitions de type
lsp definition models.py --scope BaseModel --mode type_definition

Conseils de Performance

# Utiliser outline au lieu de lire des fichiers entiers
lsp outline large_file.py  # Mieux que : read large_file.py

# Utiliser les chemins de symbole pour les structures imbriquées (plus précis que les numéros de ligne)
lsp definition models.py --scope User.Profile.validate

# Limiter les résultats dans les grandes bases de code
lsp search "User" --max-items 20

# Utiliser doc pour comprendre les APIs sans naviguer vers la source
lsp doc api.py --scope fetch_data  # Obtenir la doc/les types sans sauter à la définition

# Vérifier les chaînes locate si les commandes échouent
lsp locate main.py --scope 42 --find "<|>my_var"

Guides Spécifiques au Domaine

Pour les scénarios spécialisés, voir :

Monorepo : monorepo.md
Frontend : bp_frontend.md
Backend : bp_backend.md