Skip to main content
Publicamos atualizações frequentes em nossa documentação, e a tradução desta página ainda pode estar em andamento. Para obter as informações mais atualizadas, acesse a documentação em inglês.
All products
Segurança do código

Como testar arquivos de ajuda de consulta

Neste artigo

Você pode usar os dados da CodeQL CLI para visualizar os arquivos de ajuda de consulta como Markdown e garantir que eles sejam válidos.

O CodeQL do GitHub é licenciado por usuário após a instalação. Você pode usar o CodeQL somente para determinadas tarefas sob as restrições de licença. Para obter mais informações, confira "Sobre a CLI do CodeQL".

Se você tiver uma licença do GitHub Advanced Security, poderá usar o CodeQL para análise automatizada, integração contínua e entrega contínua. Para obter mais informações, confira "Sobre a Segurança Avançada do GitHub".

Observação: este artigo foi migrado do site de documentação do CodeQL em janeiro de 2023.

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 bancos de dados com a CodeQL CLI".

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>]

em que <qhelp|query|dir|suite> é um dos seguintes:

  • 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.
  • o caminho para um conjunto de consultas ou o nome de um conjunto de consultas conhecido para um pacote do CodeQL. Para obter mais informações, confira "Como criar conjuntos de consultas do CodeQL".

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 obter mais informações, confira "generate query-help".

Leitura adicional