Como criar e trabalhar com pacotes do CodeQL

Sobre os pacotes do CodeQL e a CodeQL CLI

Com os pacotes do CodeQL e os comandos de gerenciamento de pacotes na CodeQL CLI, você pode publicar as consultas personalizadas e integrá-las à análise de base de código.

Há dois tipos de pacotes do CodeQL: pacotes de consultas e pacotes de biblioteca.

• Os pacotes de consultas foram projetados para serem executados. Quando um pacote de consultas é publicado, ele inclui todas as dependências transitivas e um cache de compilação. Isso garante a execução consistente e eficiente das consultas no pacote.
• Os pacotes de biblioteca são projetados para serem usados por pacotes de consultas (ou outros pacotes de biblioteca) e não contêm consultas. As bibliotecas não são compiladas e não há nenhum cache de compilação incluído quando o pacote é publicado.

Você pode usar o comando pack na CodeQL CLI para criar pacotes do CodeQL, adicionar dependências a pacotes e instalar ou atualizar dependências. Você também pode publicar e baixar pacotes do CodeQL usando o comando pack. Para obter mais informações, confira "Publicar e usar pacotes do CodeQL".

Como criar um pacote do CodeQL

Você pode criar um pacote do CodeQL executando o seguinte comando na raiz de check-out do projeto:

codeql pack init <scope>/<pack>

É preciso especificar:

• <scope>: o nome da organização do GitHub ou da conta de usuário de destino da publicação.

• <pack>: o nome do pacote que você está criando.

O comando codeql pack init cria a estrutura de diretório e os arquivos de configuração de um pacote do CodeQL. Por padrão, o comando cria um pacote de consultas. Se você quiser criar um pacote de biblioteca, edite o arquivo qlpack.yml para declará-lo explicitamente como um pacote de biblioteca, incluindo a propriedade library:true.

Como modificar um pacote QL herdado existente para criar um pacote do CodeQL

Se você já tiver um arquivo qlpack.yml, edite-o manualmente para convertê-lo em um pacote do CodeQL.

1. Edite a propriedade name para que ela corresponda ao formato <scope>/<name>, em que <scope> é o nome da organização do GitHub ou da conta de usuário de destino da publicação.

2. No arquivo qlpack.yml, inclua uma propriedade version com um identificador semver, bem como um bloco opcional dependencies.

3. Migre a lista de dependências no libraryPathDependencies para o bloco dependencies. Especifique o intervalo de versão de cada dependência. Se o intervalo não for importante ou você não tiver certeza da compatibilidade, especifique "\*" para indicar que qualquer versão é aceitável e o padrão será a mais recente quando codeql pack install for executado.

Para obter mais informações sobre as propriedades, confira "Como personalizar a análise com pacotes CodeQL".

Adicionar e instalar dependências a um pacote do CodeQL

Você pode adicionar dependências em pacotes do CodeQL usando o comando codeql pack add. Você precisa especificar o escopo, o nome e (opcionalmente) um intervalo de versão compatível.

codeql pack add <scope>/<name>@x.x.x <scope>/<other-name>

Se você não especificar um intervalo de versão, a versão mais recente será adicionada. Caso contrário, a versão mais recente que atenda ao intervalo solicitado será adicionada.

Esse comando atualiza o arquivo qlpack.yml com as dependências solicitadas e as baixa no cache de pacote. Observe que esse comando reformatará o arquivo e removerá todos os comentários.

Você também pode editar manualmente o arquivo qlpack.yml para incluir dependências e instalá-las com o comando:

codeql pack install

Esse comando baixa todas as dependências no cache compartilhado no disco local.