Como testar arquivos de ajuda de consulta

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 saber mais, 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 em stdout.

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 saber mais, confira generate query-help.

Leitura adicional

• Arquivos de ajuda de consulta