Acerca de la prueba de archivos de ayuda de consulta
Prueba los archivos de ayuda de consulta representándolos como Markdown para asegurarte de que son válidos antes de cargarlos en el repositorio de CodeQL o usarlos en el análisis de código.
La ayuda de consulta es documentación que acompaña a una consulta para explicar cómo funciona, así como para proporcionar información sobre el posible problema que identifica la consulta. Es recomendable escribir ayuda de consulta para todas las consultas nuevas. Para obtener más información, consulta "Contribución a CodeQL" en el repositorio de CodeQL.
La CodeQL CLI incluye un comando para probar la ayuda de consulta y representar el contenido como Markdown, de modo que puedas obtener fácilmente una vista previa del contenido en el IDE. Usa el comando para validar los archivos de ayuda de consulta antes de cargarlos en el repositorio de CodeQL o compartirlos con otros usuarios. A partir de la versión 2.7.1 de la CodeQL CLI, también puedes incluir la ayuda de consulta representada por Markdown en los archivos SARIF generados durante los análisis de CodeQL para que la ayuda de consulta se pueda mostrar en la interfaz de análisis de código. Para obtener más información, vea «Análisis del código con consultas de CodeQL».
Prerrequisitos
- El archivo de ayuda de consulta (
.qhelp) debe tener un archivo de consulta asociado (.ql) con un nombre base idéntico. - El archivo de ayuda de consulta debe seguir la estructura y el estilo estándares de la documentación de ayuda de consulta. Para obtener más información, consulta la guía de estilo de la ayuda de consulta en el repositorio de CodeQL.
En ejecución codeql generate query-help
Puedes probar los archivos de ayuda de consulta ejecutando el siguiente comando:
codeql generate query-help <qhelp|query|dir|suite> --format=<format> [--output=<dir|file>]
Para este comando <qhelp|query|dir|suite> debe ser la ruta de acceso a un archivo .qhelp, la ruta de acceso a un archivo .ql, la ruta de acceso a un directorio que contiene consultas y archivos de ayuda de consulta, o la ruta de acceso a un conjunto de consultas.
Debes especificar una opción --format, la cual define cómo se representa la ayuda de consulta. Actualmente, debes especificar markdown para representar la ayuda de consulta como Markdown.
La opción --output define una ruta de acceso de archivo donde se guardará la ayuda de consulta representada.
- Para los directorios que contienen archivos
.qhelpo conjuntos de consultas que definen uno o varios archivos.qhelp, debes especificar un directorio--output. Los nombres de archivo dentro del directorio de salida se derivarán de los nombres de los archivos.qhelp. - Para archivos
.qhelpo.qlindividuales, puedes especificar una opción--output. Si no especificas una ruta de acceso de salida, la ayuda de consulta representada se escribirá enstdout.
Para obtener detalles completos de todas las opciones que puedes usar al probar archivos de ayuda de consulta, lee el artículo generate query-help.
Results
Al ejecutar el comando, CodeQL intenta representar cada archivo .qhelp que tiene un archivo .ql asociado. En el caso de los archivos individuales, el contenido representado se imprime en stdout si no especificas una opción --output. Para los demás casos de uso, el contenido representado se guarda en la ruta de acceso de salida especificada.
De forma predeterminada, la CodeQL CLI imprimirá un mensaje de advertencia si:
- La ayuda de consulta no es válida; en este caso imprimirá también una descripción de los elementos de dicha ayuda de consulta que no son válidos.
- Los archivos
.qhelpespecificados en el comando no tienen el mismo nombre base que el archivo.qlque los acompaña. - Los archivos
.qlespecificados en el comando no tienen el mismo nombre base que el archivo.qhelpque los acompaña.
Puedes indicar a la CodeQL CLI cómo debe controlar estas advertencias incluyendo una opción --warnings en el comando. Para obtener más información, vea «generate query-help».