# Referência de pacotes de consulta CodeQL

Entenda a compatibilidade, os conteúdos e a estrutura dos pacotes CodeQL.

## Compatibilidade de pacotes do CodeQL

Quando um pacote de consultas é publicado, ele inclui representações pré-compiladas de todas as consultas nele para aumentar a velocidade da análise. No entanto, se a versão de CodeQL que executa a análise for mais de 6 meses mais recente do que a versão executada `codeql pack publish`, talvez seja necessário compilar as consultas da origem durante a análise, retardando significativamente o processo.

Um pacote publicado pela *mais recente* versão pública do CodeQL será utilizável pela versão do CodeQL que é usada pelo code scanning e pelo GitHub Actions, mesmo que essa versão seja geralmente um pouco mais antiga.

Se sua análise contiver linhas como a seguinte, CodeQL usará com êxito consultas pré-compiladas:

```shell
[42/108] Loaded /long/path/to/query/Filename.qlx.
```

Se sua análise, em vez disso, contiver linhas semelhantes às seguintes, então CodeQL recompilou manualmente as consultas das fontes originais:

```shell
Compiling query plan for /long/path/to/query/Filename.ql.
[42/108 comp 25s] Compiled /long/path/to/query/Filename.ql.
```

Recomendamos usar uma versão recente do CodeQL para publicar seus pacotes, a fim de ajudar os usuários do pacote de consultas predefinidas a se beneficiarem de consultas pré-compiladas. Além disso, você deve publicar uma nova versão do pack com uma versão atualizada CodeQL a cada 6 meses.

Se você publicar pacotes de consultas com a intenção de usá-los em uma instalação do GitHub Enterprise Server que usa os binários agrupados do CodeQL, use a mesma versão do CodeQL para executar `codeql pack publish`.

##

```
          `qlpack.yml` arquivos
```

Ao executar comandos relacionados à consulta, o CodeQL primeiro procura em diretórios no mesmo nível do diretório de instalação (e seus subdiretórios) por arquivos `qlpack.yml`, em seguida, verifica o cache de pacotes em busca de pacotes baixados CodeQL. Isso significa que, quando seus pacotes locais no diretório de instalação substituem pacotes com o mesmo nome no cache de pacotes, você pode testar suas alterações locais.

Os metadados em cada arquivo `qlpack.yml` informam ao CodeQL como compilar consultas no pacote, de quais bibliotecas o pacote depende e onde encontrar as definições do conjunto de consultas.

O conteúdo do pacote do CodeQL (consultas ou bibliotecas usadas na análise do CodeQL) está incluído no mesmo diretório que o `qlpack.yml` ou em nos subdiretórios.

O diretório que contém o arquivo `qlpack.yml` funciona como o diretório raiz do conteúdo do pacote do CodeQL. Ou seja, para todos os arquivos `.ql` e `.qll` no pacote, o CodeQL resolverá todas as instruções de importação relativas ao diretório que contém o arquivo `qlpack.yml` na raiz do pacote.

###

```
          `qlpack.yml` propriedades
```

As propriedades a seguir são compatíveis com arquivos `qlpack.yml`.

#### `name`

* Exigido por todos os pacotes.
* Define o escopo do pacote, em que o pacote do CodeQL é publicado e o nome do pacote é definido usando caracteres alfanuméricos e hifens. Esse campo precisa ser exclusivo, pois o CodeQL não pode diferenciar pacotes do CodeQL com nomes idênticos. Use o nome do pacote para especificar as consultas a serem executadas usando `database analyze` e para definir dependências entre pacotes do CodeQL (veja os exemplos abaixo). Por exemplo:

  ```yaml
  name: octo-org/security-queries
  ```

#### `version`

* Exigido por todos os pacotes publicados.
* Define uma versão semântica desse pacote do CodeQL que precisa seguir à [especificação SemVer v2.0.0](https://semver.org/spec/v2.0.0.html). Por exemplo:

  ```yaml
  version: 0.0.0
  ```

#### `dataExtensions`

* Exigido por pacotes de modelos.
* Obtém uma lista de padrões glob que especificam onde os arquivos de extensão de dados estão localizados em relação à raiz do pacote de consulta ou pacote de bibliotecas.

#### `dependencies`

* Exigido por pacotes de consultas e bibliotecas que definem as dependências de pacote do CodeQL em outros pacotes. Pacotes de modelos não podem definir dependências e, em vez disso, usam `extensionTargets`.
* Define um mapa de referências de pacote para o intervalo de versão semântica compatível com esse pacote. Compatível com a CodeQL CLI versões v2.6.0 e posteriores. Por exemplo:

  ```yaml
  dependencies:
    codeql/cpp-all: ^0.0.2
  ```

  Se você não tiver certeza ou não importa qual versão deve ser usada, então pode usar `"*"`, o que indica que qualquer versão dessa dependência é compatível com este pacote. Na prática, isso geralmente será resolvido para a versão publicada mais alta da dependência.

  Há um espaço reservado de versão especial, `${workspace}`, que indica que esse pacote do CodeQL depende de qualquer versão da dependência no mesmo espaço de trabalho. Para saber mais, confira [Sobre os workspaces do CodeQL](/pt/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/about-codeql-workspaces#using-workspace-as-a-version-range-in-qlpackyml-files).

#### `defaultSuiteFile`

* Exigido por pacotes que exportam um conjunto de consultas padrão para execução.
* Define o caminho para um arquivo de pacote de consultas em relação à raiz do pacote, contendo todas as consultas que são executadas por padrão quando esse pacote é passado para o comando `codeql database analyze`. Compatível com a CLI versão v2.6.0 e posteriores. Só é possível definir `defaultSuiteFile` ou `defaultSuite`. Por exemplo:

  ```yaml
  defaultSuiteFile: cpp-code-scanning.qls
  ```

#### `defaultSuite`

* Exigido por pacotes que exportam um conjunto de consultas padrão para execução.
* Define um conjunto de consultas embutidas que contém todas as consultas que são executadas por padrão quando esse pacote é passado para o comando `codeql database analyze`. Compatível com a CLI versão v2.6.0 e posteriores. Só é possível definir `defaultSuiteFile` ou `defaultSuite`. Por exemplo:

  ```yaml
  defaultSuite:
    queries: .
    exclude:
      precision: medium
  ```

#### `extensionTargets`

* Exigido por pacotes de modelos.
* Declara a quais pacotes de consultas as extensões no pacote de modelos se aplicam. O pacote de extensões injetará suas extensões de dados em cada pacote nomeado no dicionário `extensionTargets`, se o pacote estiver dentro do intervalo de versão especificado e for usado na avaliação.

#### `groups`

* Opcional.
* Define agrupamentos lógicos de pacotes em um espaço de trabalho do CodeQL. Usar grupos é uma maneira de aplicar operações de pacote a subconjuntos de pacotes em um espaço de trabalho. Por exemplo, o pacote a seguir é definido para fazer parte dos grupos `java` e `experimental`:

  ```yaml
  groups:
    - java
    - experimental
  ```

  A execução de `codeql pack publish --groups java,-experimental` publicará todos os pacotes no grupo `java`, *exceto* os pacotes `experimental`. Você pode executar o comando `codeql pack ls --groups [-]<group>[,[-]<group>...]` para listar os pacotes em um espaço de trabalho que correspondem ao conjunto especificado de grupos.

  Um pacote do CodeQL no espaço de trabalho fornecido será incluído na lista se:

  * Ele estiver em, pelo menos, um dos grupos listados sem um sinal de subtração (essa condição será atendida automaticamente se não houver grupos listados sem um sinal de subtração) e
  * Ele não estiver em nenhum grupo listado com um sinal de subtração.

#### `library`

* Exigido por pacotes de biblioteca.
* Define um valor booliano que indica se esse pacote é ou não um pacote de biblioteca. Os pacotes de biblioteca não contêm consultas e não são compilados. Os pacotes de consultas podem ignorar esse campo ou defini-lo explicitamente como `false`. Por exemplo:

  ```yaml
  library: true
  ```

#### `suites`

* Opcional para pacotes que definem conjuntos de consultas. Isso permite que os usuários executem conjuntos de consultas armazenados no diretório especificado especificando o nome do pacote, sem fornecer o caminho completo.
* Atualmente com suporte apenas para os pacotes de consulta padrão incluídos no pacote da CLI do CodeQL.
* Esta opção não tem suporte para pacotes do CodeQL baixados do registro de contêiner do GitHub.

#### `tests`

* Opcional para pacotes que contêm testes do CodeQL. Ignorado para pacotes sem testes.
* Define o caminho para um diretório dentro do pacote que contém testes, definido em relação ao diretório do pacote. Use `.` para especificar o pacote inteiro. Todas as consultas nesse diretório são executadas como testes quando `test run` é executado com a opção `--strict-test-discovery`. Essas consultas são ignoradas por definições de conjunto de consultas que usam instruções `queries` ou `qlpack` para solicitar todas as consultas em um pacote específico. Se essa propriedade estiver ausente, `.` será assumido. Por exemplo:

  ```yaml
  tests: .
  ```

#### `extractor`

* Exigido por todos os pacotes que contêm testes do CodeQL.
* Define o extrator de linguagem do CodeQL a ser usado ao executar os testes do CodeQL no pacote. Para obter mais informações sobre como testar as consultas, confira [Testar consultas personalizadas](/pt/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/testing-custom-queries). Por exemplo:

  ```yaml
  extractor: javascript-typescript
  ```

#### `authors`

* Opcional.
* Define os metadados que serão exibidos na página de pesquisa de empacotamento na seção de pacotes da conta em que o pacote do CodeQL foi publicado. Por exemplo:

  ```yaml
  authors: author1@github.com,author2@github.com
  ```

#### `license`

* Opcional.
* Define os metadados que serão exibidos na página de pesquisa de empacotamento na seção de pacotes da conta em que o pacote do CodeQL foi publicado. Para obter uma lista de licenças permitidas, confira [Lista de licenças SPDX](https://spdx.org/licenses/) na Especificação SPDX. Por exemplo:

  ```yaml
  license: MIT
  ```

#### `description`

* Opcional.
* Define os metadados que serão exibidos na página de pesquisa de empacotamento na seção de pacotes da conta em que o pacote do CodeQL foi publicado. Por exemplo:

  ```yaml
  description: Human-readable description of the contents of the CodeQL pack.
  ```

#### `libraryPathDependencies`

* Opcionalmente, encerrando. Use a propriedade `dependencies`.
* Usado anteriormente para definir os nomes de qualquer pacote do CodeQL dos quais esse pacote do CodeQL depende, como uma matriz. Fornece ao pacote acesso a todas as bibliotecas, esquemas de banco de dados e conjuntos de consultas definidos na dependência. Por exemplo:

  ```yaml
  libraryPathDependencies: codeql/javascript-all
  ```

#### `dbscheme`

* Exigido apenas por pacotes de linguagens principais.
* Define o caminho para o [esquema de banco de dados](https://codeql.github.com/docs/codeql-overview/codeql-glossary/#codeql-database-schema) para todas as bibliotecas e consultas escritas para essa linguagem do CodeQL (veja o exemplo abaixo). Por exemplo:

  ```yaml
  dbscheme: semmlecode.python.dbscheme
  ```

#### `upgrades`

* Exigido apenas por pacotes de linguagens principais.
* Define o caminho para um diretório dentro do pacote que contém scripts de atualização de banco de dados, definidos em relação ao diretório do pacote. As atualizações de banco de dados são usadas internamente para garantir que um banco de dados criado com uma versão diferente da CodeQL CLI seja compatível com a versão atual da CLI. Por exemplo:

  ```yaml
  upgrades: .
  ```

#### `warnOnImplicitThis`

* Opcional. O padrão será definido como `false` se a propriedade `warnOnImplicitThis` não for definida.
* Define um booliano que especifica se o compilador deve ou não emitir avisos sobre chamadas de predicado de membro com receptores de chamada `this` implícitos, ou seja, sem um receptor explícito. Disponível desde CodeQL CLI v2.13.2. Por exemplo:

  ```yaml
  warnOnImplicitThis: true
  ```

##

```
          `codeql-pack.lock.yml` arquivos

          Os arquivos `codeql-pack.lock.yml` armazenam as versões das dependências transitivas resolvidas de um pacote do CodeQL. Esse arquivo será criado pelo comando `codeql pack install` se ele ainda não existir e deverá ser adicionado ao sistema de controle de versão. A seção `dependencies` do arquivo `qlpack.yml`contém intervalos de versão compatíveis com o pacote. O arquivo `codeql-pack.lock.yml` bloqueia as versões para dependências precisas. Isso garante que a execução de `codeql pack install` nesse pacote sempre recupere as mesmas versões de dependências, mesmo que existam versões compatíveis mais recentes.
```

Por exemplo, se um arquivo `qlpack.yml` contiver as seguintes dependências:

```yaml
dependencies:
  codeql/cpp-all: ^0.1.2
  my-user/my-lib: ^0.2.3
  other-dependency/from-source: "*"
```

O arquivo `codeql-pack.lock.yml` conterá algo semelhante ao seguinte:

```yaml
dependencies:
  codeql/cpp-all:
    version: 0.1.4
  my-user/my-lib:
    version: 0.2.4
  my-user/transitive-dependency:
    version: 1.2.4
```

A dependência `codeql/cpp-all` está bloqueada para a versão 0.1.4. A dependência `my-user/my-lib` está bloqueada para a versão 0.2.4. O `my-user/transitive-dependency`, que é uma dependência transitiva e não é especificado no arquivo `qlpack.yml`, está bloqueado para a versão 1.2.4. O `other-dependency/from-source` está ausente do arquivo de bloqueio, pois é resolvido da origem. Essa dependência precisa estar disponível no mesmo workspace do CodeQL que o pacote. Para obter mais informações sobre os workspaces do CodeQL e resolver dependências por meio da origem, confira [Sobre os workspaces do CodeQL](/pt/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/about-codeql-workspaces).

Na maioria dos casos, o arquivo `codeql-pack.lock.yml` só é relevante para pacotes de consulta, pois os pacotes de biblioteca não são executáveis e geralmente não precisam que as dependências transitivas sejam corrigidas. A exceção a isso é para pacotes de biblioteca que contêm testes. Nesse caso, o arquivo `codeql-pack.lock.yml` é usado para garantir que os testes sejam sempre executados com as mesmas versões de dependências para evitar falhas falsas quando houver dependências incompatíveis.

## Pacotes personalizados de exemplo CodeQL

Você deve salvar arquivos para consultas e testes personalizados em pacotes separados e organizar pacotes personalizados em pastas específicas para cada idioma de destino.

### Pacotes do CodeQL para bibliotecas personalizadas

Um pacote personalizado do CodeQL que contém bibliotecas C++ personalizadas, sem consultas ou testes, pode ter um arquivo `qlpack.yml` contendo:

```yaml
name: my-github-user/my-custom-libraries
version: 1.2.3
library: true
dependencies:
  codeql/cpp-all: ^0.1.2
```

em que `codeql/cpp-all` é o nome do pacote do CodeQL para análise do C/C++ incluído no repositório do CodeQL. O intervalo de versão `^0.1.2` indica que esse pacote é compatível com todas as versões do `codeql/cpp-all` iguais ou superiores à `0.1.2` e inferiores a `0.2.0`. Qualquer arquivo de biblioteca do CodeQL (um arquivo com uma extensão `.qll`) definido nesse pacote estará disponível para consultas definidas em qualquer pacote de consultas que inclua esse pacote no bloco de dependências.

A propriedade `library` indica que esse pacote é um pacote de biblioteca e não contém nenhuma consulta.

### Pacotes do CodeQL para consultas personalizadas

Um pacote personalizado do CodeQL que contém consultas e bibliotecas C++ personalizadas pode ter um arquivo `qlpack.yml` contendo:

```yaml
name: my-github-user/my-custom-queries
version: 1.2.3
dependencies:
  codeql/cpp-all: ^0.1.2
  my-github-user/my-custom-libraries: ^1.2.3
```

em que `codeql/cpp-all` é o nome do pacote do CodeQL para análise do C/C++ incluído no repositório do CodeQL. O intervalo de versão `^0.1.2` indica que esse pacote é compatível com todas as versões do `codeql/cpp-all` iguais ou superiores à `0.1.2` e inferiores a `0.2.0`.
`my-github-user/my-custom-libraries` é o nome de um pacote do CodeQL que contém bibliotecas personalizadas do CodeQL para C++. Qualquer arquivo de biblioteca do CodeQL (um arquivo com uma extensão `.qll`) definido neste pacote estará disponível para consultas no pacote `my-github-user/my-custom-queries`.

### Pacotes do CodeQL para testes personalizados

Para pacotes personalizados do CodeQL que contêm arquivos de teste, você também precisa incluir uma propriedade `extractor` para que o comando `test run` saiba como criar bancos de dados de teste. Você também pode especificar a propriedade `tests`.

O arquivo `qlpack.yml` a seguir informa que `my-github-user/my-query-tests` depende de `my-github-user/my-custom-queries` em uma versão igual ou superior a 1.2.3 e inferior a 2.0.0. Ele também declara que a CLI deve usar o Java `extractor` ao criar bancos de dados de teste. A linha `tests: .` declara que todos os arquivos `.ql` no pacote devem ser executados como testes quando `codeql test run` é executado com a opção `--strict-test-discovery`. Normalmente, os pacotes de teste não contêm uma propriedade `version`. Isso impede que você os publique acidentalmente.

```yaml
name: my-github-user/my-query-tests
dependencies:
  my-github-user/my-custom-queries: ^1.2.3
extractor: java-kotlin
tests: .
```

Para obter mais informações sobre como executar testes, confira [Testar consultas personalizadas](/pt/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/testing-custom-queries).

## Exemplos de pacotes CodeQL no repositório CodeQL

Cada uma das linguagens no repositório do CodeQL tem quatro pacotes principais do CodeQL:

* Pacote de biblioteca principal da linguagem, com o esquema de banco de dados usado pela linguagem e as bibliotecas e consultas do CodeQL em `<language>/ql/lib`

* Pacote de consultas principal para a linguagem que inclui as consultas padrão das linguagens, juntamente com os conjuntos de consultas em `<language>/ql/src`

* Testes para as principais bibliotecas e consultas de linguagem em `<language>/ql/test`

* Exemplo de consultas para a linguagem em `<language>/ql/examples`

### Pacote de biblioteca principal

Veja um arquivo de exemplo `qlpack.yml` do pacote de linguagem principal das [bibliotecas de análise do C/C++](https://github.com/github/codeql/blob/main/cpp/ql/lib/qlpack.yml):

```yaml
name: codeql/cpp-all
version: x.y.z-dev
dbscheme: semmlecode.cpp.dbscheme
library: true
upgrades: upgrades
```

Algumas observações adicionais sobre as seguintes propriedades:

* ```
          `library`: indica que esse é um pacote de biblioteca sem consultas executáveis. Ele só deve ser usado como uma dependência de outros pacotes.
  ```

* ```
          `dbscheme` e `upgrades`: essas propriedades são internas à CodeQL CLI e só devem ser definidas no pacote principal de consultas do CodeQL para um idioma.
  ```

### Pacote de consultas principal

Veja um arquivo de exemplo `qlpack.yml` de pacote de consultas principal de [consultas de análise do C/C++](https://github.com/github/codeql/blob/main/cpp/ql/src/qlpack.yml):

```yaml
name: codeql/cpp-queries
version: x.y.z-dev
dependencies:
    codeql/cpp-all: "*"
    codeql/suite-helpers: "*"
suites: codeql-suites
defaultSuiteFile: codeql-suites/cpp-code-scanning.qls
```

Algumas observações adicionais sobre as seguintes propriedades:

* ```
          `dependencies`: esse pacote de consultas depende de `codeql/cpp-all` e `codeql/suite-helpers`. Como essas dependências são resolvidas na origem, não importa com qual versão do pacote do CodeQL elas são compatíveis. Para obter mais informações de como resolver as dependências por meio da origem, confira [Dependências de origem](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/about-codeql-workspaces#source-dependencies).
  ```

* ```
          `suites`: indica o diretório que contém conjuntos de consultas "conhecidos".
  ```

* ```
          `defaultSuiteFile`: o nome do arquivo do pacote de consultas padrão usado quando nenhum pacote de consultas é especificado.
  ```

### Testes para o pacote principal do CodeQL

Veja um arquivo de exemplo `qlpack.yml` do pacote de teste principal para [testes de análise do C/C++](https://github.com/github/codeql/blob/main/cpp/ql/src/qlpack.yml):

```yaml
name: codeql/cpp-tests
dependencies:
  codeql/cpp-all: "*"
  codeql/cpp-queries: "*"
extractor: cpp
tests: .
```

Algumas observações adicionais sobre as seguintes propriedades:

* ```
          `dependencies`: esse pacote depende da consulta principal do CodeQL e dos pacotes de biblioteca para C++.
  ```

* ```
          `extractor`: especifica que todos os testes usarão o mesmo extrator C++ para criar o banco de dados para os testes.
  ```

* ```
          `tests`: especifica o local dos testes. Nesse caso, os testes estão na pasta raiz (e em todas as subpastas) do pacote.
  ```

* ```
          `version`: não há nenhuma propriedade `version` para o pacote de testes. Isso impede que os pacotes de teste sejam publicados acidentalmente.
  ```