Sobre os testes de arquivos de ajuda de consulta
Teste os arquivos de ajuda de consulta renderizando-os como Markdown para verificar se eles são válidos antes de carregá-los no repositório do CodeQL ou usá-los na verificação de código.
A ajuda de consulta é a documentação que acompanha uma consulta para explicar como a consulta funciona, além de fornecer informações sobre o possível problema identificado pela consulta. Uma boa prática é escrever a ajuda de consulta para todas as novas consultas. Para obter mais informações confira "Como contribuir para o CodeQL" no repositório do CodeQL.
A CodeQL CLI inclui um comando para testar a ajuda de consulta e renderizar o conteúdo como markdown, para que você possa visualizar facilmente o conteúdo no IDE. Use o comando para validar arquivos de ajuda de consulta antes de carregá-los no repositório do CodeQL ou compartilhá-los com outros usuários. Da CodeQL CLI 2.7.1 em diante, você também pode incluir a ajuda de consulta renderizada por markdown nos arquivos SARIF gerados durante as análises do CodeQL para que a ajuda de consulta possa ser exibida na interface do usuário de verificação de código. Para obter mais informações, confira "Como analisar o código com as consultas CodeQL".
Pré-requisitos
- O arquivo de ajuda de consulta (
.qhelp
) precisa ter um arquivo de consulta (.ql
) que o acompanha com um nome base idêntico. - O arquivo de ajuda de consulta deve seguir a estrutura e o estilo padrão da documentação da ajuda de consulta. Para obter mais informações, confira o Guia de estilo de ajuda de consulta no repositório do CodeQL.
Em execuçãocodeql generate query-help
Você pode testar arquivos de ajuda de consulta executando o seguinte comando:
codeql generate query-help <qhelp|query|dir|suite> --format=<format> [--output=<dir|file>]
Para esse comando, <qhelp|query|dir|suite>
deve ser o caminho para um arquivo .qhelp
, o caminho para um arquivo .ql
, o caminho para um diretório que contém consultas e arquivos de ajuda de consulta ou o caminho para um conjunto de consultas.
Você precisa especificar uma opção --format
, que define como a ajuda de consulta é renderizada. No momento, você precisa especificar markdown
para renderizar a ajuda de consulta como markdown.
A opção --output
define um caminho de arquivo em que a ajuda de consulta renderizada será salva.
- Para diretórios que contêm arquivos ou conjuntos de consultas
.qhelp
que definem um ou mais arquivos.qhelp
, você precisa especificar um diretório--output
. Os nomes de arquivo no diretório de saída serão derivados dos nomes de arquivo.qhelp
. - Para arquivos individuais
.qhelp
ou.ql
, você pode especificar uma opção--output
. Se você não especificar um caminho de saída, a ajuda de consulta renderizada será escrita emstdout
.
Para ver os detalhes completos de todas as opções que você pode usar ao testar arquivos de ajuda de consulta, confira "generate query-help".
Resultados
Quando você executa o comando, o CodeQL tenta renderizar cada arquivo .qhelp
que tem um arquivo .ql
que o acompanha. Para arquivos individuais, o conteúdo renderizado será impresso em stdout
se você não especificar uma opção --output
. Para todos os outros casos de uso, o conteúdo renderizado é salvo no caminho de saída especificado.
Por padrão, a CodeQL CLI imprimirá uma mensagem de aviso se:
- Uma das ajudas de consulta for inválida, juntamente com uma descrição dos elementos de ajuda de consulta inválidos
- Algum dos arquivos
.qhelp
especificados no comando não tiver o mesmo nome base que um arquivo.ql
que o acompanhe - Algum dos arquivos
.ql
especificados no comando não tiver o mesmo nome base que um arquivo.qhelp
que o acompanhe
Você pode informar à CodeQL CLI como lidar com esses avisos incluindo uma opção --warnings
no comando. Para obter mais informações, confira "generate query-help".