Test des fichiers d’aide aux requêtes

À propos du test des fichiers d’aide aux requêtes

Testez les fichiers d’aide aux requêtes en les restituant au format Markdown pour vous assurer qu’ils sont valides avant de les charger dans le dépôt CodeQL ou de les utiliser dans l’analyse du code.

L’aide aux requêtes est une documentation qui accompagne une requête pour expliquer le fonctionnement de la requête et pour fournir des informations sur le problème potentiel identifié par la requête. Il est recommandé d’écrire une aide aux requêtes pour toutes les nouvelles requêtes. Pour plus d’informations, consultez « Contribution à CodeQL » dans le dépôt CodeQL.

CodeQL CLI comprend une commande pour tester l’aide aux requêtes et restituer le contenu au format Markdown afin de vous permettre de prévisualiser facilement le contenu dans votre IDE. Utilisez la commande pour valider les fichiers d’aide aux requêtes avant de les charger dans le dépôt CodeQL ou de les partager avec d’autres utilisateurs. À partir de CodeQL CLI 2.7.1 et ultérieur, vous pouvez aussi inclure l’aide aux requête restituée en Markdown dans les fichiers SARIF générés pendant les analyses CodeQL afin que l’aide aux requêtes puisse être affichée dans l’interface utilisateur de l’analyse du code. Pour plus d’informations, consultez « Analyse de votre code avec des requêtes CodeQL ».

Prérequis

• Le fichier d’aide aux requêtes (.qhelp) doit avoir un fichier de requête (.ql) associé avec un nom de base identique.
• Le fichier d’aide aux requêtes doit suivre la structure et le style standard de la documentation de l’aide aux requêtes. Pour plus d’informations, consultez le Guide de style de l’aide aux requêtes dans le dépôt CodeQL.

En cours d’exécution codeql generate query-help

Vous pouvez tester les fichiers d’aide aux requêtes en exécutant la commande suivante :

codeql generate query-help <qhelp|query|dir|suite> --format=<format> [--output=<dir|file>]

Pour cette commande, <qhelp|query|dir|suite> doit être le chemin d’accès à un fichier .qhelp, le chemin d’accès à un fichier .ql, le chemin d’accès à un répertoire contenant des requêtes et des fichiers d’aide de requête ou le chemin d’accès à une suite de requêtes.

Vous devez spécifier une option --format qui définit comment l’aide aux requêtes est restituée. Actuellement, vous devez spécifier markdown pour restituer l’aide aux requêtes au format Markdown.

L’option --output définit un chemin de fichier dans lequel l’aide aux requêtes restituée sera enregistrée.

• Pour les répertoires contenant des fichiers .qhelp ou des suites de requêtes définissant un ou plusieurs fichiers .qhelp, vous devez spécifier un répertoire --output. Les noms de fichier dans le répertoire de sortie sont dérivés des noms de fichier .qhelp.
• Pour les fichiers .qhelp ou .ql seuls, vous pouvez spécifier une option --output. Si vous ne spécifiez pas de chemin de sortie, l’aide aux requêtes restituée est écrite en stdout.

Pour des détails complets sur toutes les options que vous pouvez utiliser lors d’un test de fichiers d’aide aux requêtes, consultez « generate query-help ».

Résultats

Lorsque vous exécutez la commande, CodeQL tente de restituer chaque fichier .qhelp qui a un fichier .ql associé. Pour les fichiers uniques, le contenu restitué est affiché en stdout si vous ne spécifiez pas une option --output. Pour tous les autres cas d’usage, le contenu restitué est enregistré dans le chemin de sortie spécifié.

Par défaut, CodeQL CLI affiche un message d’avertissement si :

• Des éléments dans l’aide aux requêtes ne sont pas valides, avec une description de ces éléments d’aide aux requêtes non valides
• Les fichiers .qhelp spécifiés dans la commande n’ont pas le même nom de base qu’un fichier .ql associé
• Les fichiers .ql spécifiés dans la commande n’ont pas le même nom de base qu’un fichier .qhelp associé

Vous pouvez indiquer à CodeQL CLI comment gérer ces avertissements en incluant une option --warnings dans votre commande. Pour plus d’informations, consultez « generate query-help ».

Pour aller plus loin

• « Fichiers d’aide aux requêtes »