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ção codeql 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 obter detalhes completos sobre todas as opções que você pode usar ao testar arquivos de ajuda para consulta, consulte gerar consulta-ajuda.

Results

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 gerar consulta-ajuda.

Leitura adicional

•           [Arquivos de ajuda para consulta](https://codeql.github.com/docs/writing-codeql-queries/query-help-files/#query-help-files)