# Ссылка на пакеты запросов CodeQL

Понять совместимость, содержимое и структуру пакетов CodeQL.

## CodeQL совместимость пакетов

Когда пакет запросов публикуется, он включает заранее скомпилированные представления всех запросов в нём для увеличения скорости анализа. Однако если версия CodeQL, выполняющая анализ, более чем на 6 месяцев новее запущенной версии `codeql pack publish`, может потребоваться компилировать запросы из исходного кода во время анализа, что значительно замедляет процесс.

Пакет, опубликованный *в последнем* публичном выпуске CodeQL, будет использоваться версией CodeQL, используемой code scanning и GitHub Actions, хотя это часто немного более старый релиз.

Если ваш анализ содержит следующие строки, то CodeQL успешно использует заранее скомпилированные запросы:

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

Если ваш анализ содержит строки, выглядящие следующим образом, то CodeQL вручную перекомпилировал запросы из исходного источника:

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

Чтобы помочь пользователям вашего пакета запросов воспользоваться заранее скомпилированными запросами, мы рекомендуем использовать недавний релиз CodeQL для публикации ваших пакетов. Кроме того, каждые 6 месяцев публикуйте свежую версию вашего пака с обновлённой версией CodeQL.

Если вы публикуете пакеты запросов с намерением их использования в установке GitHub Enterprise Server, которая использует свои упакованные двоичные файлы CodeQL, используйте ту же версию CodeQL для запуска `codeql pack publish`.

## файлы `qlpack.yml`

При выполнении команд, связанных с запросами, CodeQL сначала ищет файлы в родственниках инсталляционного каталога (и их подкаталогах `qlpack.yml` ), затем проверяет кэш пакетов на наличие загруженных CodeQL пакетов. Это значит, что когда ваши локальные пакеты в каталоге установки переопределяют пакеты с тем же названием в кэше пакетов, вы можете протестировать локальные изменения.

Метаданные в каждом `qlpack.yml` файле сообщают CodeQL, как скомпилировать все запросы в пакете, какие библиотеки зависят от пакета и где найти определения набора запросов.

Содержимое пакета CodeQL (запросы или библиотеки, используемые в анализе CodeQL , включаются в тот же каталог, что `qlpack.yml`и вложенные каталоги.

Каталог, `qlpack.yml` содержащий файл, служит корневым каталогом для содержимого пакета CodeQL . То есть для всех `.ql` и `.qll` файлов в пакете CodeQL разрешает все инструкции импорта относительно каталога, `qlpack.yml` содержащего файл в корневом каталоге пакета.

### свойства `qlpack.yml`

Следующие свойства поддерживаются в `qlpack.yml` файлах.

#### `name`

* Обязательный для всех пакетов.
* Определяет область пакета, в которой публикуется пакет CodeQL и имя пакета, определенного с использованием буквенно-цифровых символов и дефисов. Он должен быть уникальным, так как CodeQL не может различать пакеты CodeQL с идентичными именами. Используйте имя пакета, чтобы указать запросы для выполнения и `database analyze` определения зависимостей между пакетами CodeQL (см. примеры ниже). Рассмотрим пример.

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

#### `version`

* Требуется для всех опубликованных пакетов.
* Определяет семантику версии этого пакета CodeQL, который должен соответствовать [спецификации](https://semver.org/spec/v2.0.0.html) SemVer версии 2.0.0. Рассмотрим пример.

  ```yaml
  version: 0.0.0
  ```

#### `dataExtensions`

* Требуется пакетами моделей.
* Принимает список шаблонов glOB-объектов, указывающих, где находятся файлы расширения данных относительно корневого каталога пакета запроса или пакета библиотеки.

#### `dependencies`

* Требуется для пакетов запросов и библиотек, определяющих зависимости пакетов CodeQL для других пакетов. Пакеты моделей не могут определять зависимости и использовать `extensionTargets` их.
* Определяет карту из ссылок пакета на диапазон семантических версий, совместимый с этим пакетом. Поддерживается для версий CodeQL CLI версии 2.6.0 и более поздних версий. Рассмотрим пример.

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

  Если вы не уверены или не имеет значения, какую версию следует использовать, можно использовать `"*"`, что означает, что любая версия этой зависимости совместима с этим пакетом. На практике это обычно разрешается до самой высокой опубликованной версии зависимости.

  Существует специальный заполнитель версии, `${workspace}`указывающий, что этот пакет CodeQL зависит от любой версии зависимости в той же рабочей области. Дополнительные сведения см. в разделе [Сведения о рабочих областях CodeQL](/ru/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`

* Требуется для пакетов, экспортирующих набор запросов по умолчанию для выполнения.
* Определяет путь к файлу набора запросов относительно корневого каталога пакета, содержащий все запросы, выполняемые по умолчанию при передаче этого пакета команде `codeql database analyze` . Поддерживается из cli версии 2.6.0 и более поздних версий. Можно определить только одно или только одно из `defaultSuiteFile``defaultSuite` них. Рассмотрим пример.

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

#### `defaultSuite`

* Требуется для пакетов, экспортирующих набор запросов по умолчанию для выполнения.
* Определяет встроенный набор запросов, содержащий все запросы, выполняемые по умолчанию при передаче `codeql database analyze` этого пакета в команду. Поддерживается из cli версии 2.6.0 и более поздних версий. Можно определить только одно или только одно из `defaultSuiteFile``defaultSuite` них. Рассмотрим пример.

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

#### `extensionTargets`

* Требуется пакетами моделей.
* Объявляет, к каким пакетам запросов применяются расширения в пакете модели. Пакет расширений внедряет его расширения данных в каждый пакет, который называется в `extensionTargets` словаре, если пакет попадает в указанный диапазон версий и используется в оценке.

#### `groups`

* Необязательно.
* Определяет логические группировки пакетов в рабочей области CodeQL. Использование групп — это способ применения операций пакетов к подмножествам пакетов в рабочей области. Например, следующий пакет определяется как часть `java` и `experimental` группы:

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

  При выполнении `codeql pack publish --groups java,-experimental` будут опубликованы все пакеты в `java` группе, *кроме*`experimental` пакетов. Вы можете выполнить `codeql pack ls --groups [-]<group>[,[-]<group>...]` команду, чтобы вывести список пакетов в рабочей области, которая соответствует указанному набору групп.

  Пакет CodeQL в данной рабочей области включается в список, если:

  * Он находится по крайней мере в одной из групп, перечисленных без знака минуса (это условие автоматически удовлетворяется, если нет групп, перечисленных без знака минуса), и
  * Он не находится в какой-либо группе, указанной со знаком минуса.

#### `library`

* Требуется пакетами библиотеки.
* Определяет логическое значение, указывающее, является ли этот пакет пакетом библиотеки. Пакеты библиотек не содержат запросы и не компилируются. Пакеты запросов могут игнорировать это поле или явно задать для него значение `false`. Рассмотрим пример.

  ```yaml
  library: true
  ```

#### `suites`

* Необязательно для пакетов, определяющих наборы запросов. Это позволяет пользователям запускать наборы запросов, хранящиеся в указанном каталоге, указав имя пакета, не предоставляя полный путь.
* В настоящее время поддерживается только для стандартных пакетов запросов, включенных в пакет CLI CodeQL.
* Этот параметр не поддерживается для пакетов CodeQL, скачанных из реестра контейнеров GitHub .

#### `tests`

* Необязательно для пакетов, содержащих тесты CodeQL. Игнорируется для пакетов без тестов.
* Определяет путь к каталогу в пакете, который содержит тесты, определенный относительно каталога пакета. Используется `.` для указания всего пакета. Все запросы в этом каталоге выполняются в качестве тестов при `test run` выполнении с параметром `--strict-test-discovery` . Эти запросы игнорируются определениями набора запросов, которые используют `queries` или `qlpack` инструкции для запроса всех запросов в определенном пакете. Если это свойство отсутствует, `.` предполагается. Рассмотрим пример.

  ```yaml
  tests: .
  ```

#### `extractor`

* Требуется для всех пакетов, содержащих тесты CodeQL.
* Определяет средство извлечения данных CodeQL для использования при выполнении тестов CodeQL в пакете. Дополнительные сведения о тестировании запросов см. в разделе [Тестирование пользовательских запросов](/ru/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/testing-custom-queries). Рассмотрим пример.

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

#### `authors`

* Необязательно.
* Определяет метаданные, которые будут отображаться на странице поиска упаковки в разделе пакетов учетной записи, в которую публикуется пакет CodeQL . Рассмотрим пример.

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

#### `license`

* Необязательно.
* Определяет метаданные, которые будут отображаться на странице поиска упаковки в разделе пакетов учетной записи, в которую публикуется пакет CodeQL . Список разрешенных лицензий см [. в списке](https://spdx.org/licenses/) лицензий SPDX в спецификации SPDX. Рассмотрим пример.

  ```yaml
  license: MIT
  ```

#### `description`

* Необязательно.
* Определяет метаданные, которые будут отображаться на странице поиска упаковки в разделе пакетов учетной записи, в которую публикуется пакет CodeQL . Рассмотрим пример.

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

#### `libraryPathDependencies`

* Необязательный, закрытие. Вместо него используйте свойство `dependencies`.
* Ранее использовалось для определения имен всех пакетов CodeQL, от которые зависит этот пакет CodeQL в виде массива. Это дает пакету доступ к любым библиотекам, схеме базы данных и наборам запросов, определенным в зависимости. Рассмотрим пример.

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

#### `dbscheme`

* Требуется только для основных языковых пакетов.
* Определяет путь к схеме [](https://codeql.github.com/docs/codeql-overview/codeql-glossary/#codeql-database-schema) базы данных для всех библиотек и запросов, написанных для этого языка CodeQL (см. пример ниже). Рассмотрим пример.

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

#### `upgrades`

* Требуется только для основных языковых пакетов.
* Определяет путь к каталогу в пакете, который содержит скрипты обновления базы данных, определенный относительно каталога пакета. Обновления базы данных используются внутренне для обеспечения совместимости базы данных с другой версией CodeQL CLI с текущей версией ИНТЕРФЕЙСА командной строки. Рассмотрим пример.

  ```yaml
  upgrades: .
  ```

#### `warnOnImplicitThis`

* Необязательно. Значение по умолчанию, `false` если `warnOnImplicitThis` свойство не определено.
* Определяет логическое значение, указывающее, должен ли компилятор выдавать предупреждения о вызовах предиката члена с неявными `this` приемниками вызовов, то есть без явного приемника. Доступно с CodeQL CLI версии 2.13.2. Рассмотрим пример.

  ```yaml
  warnOnImplicitThis: true
  ```

## файлы `codeql-pack.lock.yml`

```
          `codeql-pack.lock.yml` файлы хранят версии разрешенных транзитивных зависимостей пакета CodeQL. Этот файл создается командой, `codeql pack install` если она еще не существует и должна быть добавлена в систему управления версиями. 
          `dependencies` Раздел `qlpack.yml` файла содержит диапазоны версий, совместимые с пакетом. Файл `codeql-pack.lock.yml` блокирует версии с точными зависимостями. Это гарантирует, что выполнение `codeql pack install` этого пакета всегда будет получать те же версии зависимостей, даже если существуют более новые совместимые версии.
```

Например, если `qlpack.yml` файл содержит следующие зависимости:

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

Файл `codeql-pack.lock.yml` будет содержать примерно следующее:

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

Зависимость `codeql/cpp-all` заблокирована до версии 0.1.4. Зависимость `my-user/my-lib` заблокирована до версии 0.2.4. Объект `my-user/transitive-dependency`, который является транзитивной зависимостью и не указан в `qlpack.yml` файле, заблокирован на версию 1.2.4. Файл `other-dependency/from-source` блокировки отсутствует, так как он разрешается из источника. Эта зависимость должна быть доступна в той же рабочей области CodeQL, что и пакет. Дополнительные сведения о рабочих областях CodeQL и разрешении зависимостей из источника см. в разделе [Сведения о рабочих областях CodeQL](/ru/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/about-codeql-workspaces).

В большинстве случаев файл относится только к пакетам запросов, `codeql-pack.lock.yml` так как пакеты библиотек не являются исполняемыми и обычно не нуждаются в их транзитивных зависимостях для исправления. Исключением из этого является пакет библиотек, содержащий тесты. В этом случае файл используется для обеспечения того, `codeql-pack.lock.yml` чтобы тесты всегда выполнялись с одинаковыми версиями зависимостей, чтобы избежать сбой в случае несоответствия зависимостей.

## Пример пользовательских CodeQL пакетов

Вам следует сохранять файлы для пользовательских запросов и тестов в отдельных пакетах, а также организовывать их в отдельные папки для каждого целевой языка.

### Пакеты CodeQL для пользовательских библиотек

Пользовательский пакет данных CodeQL, содержащий пользовательские библиотеки C++ без запросов или тестов, может содержать `qlpack.yml` файл:

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

где `codeql/cpp-all` имя пакета CodeQL для анализа C/C++, включенного в репозиторий CodeQL. Диапазон `^0.1.2` версий указывает, что этот пакет совместим со всеми версиями `codeql/cpp-all` , превышающими или равными `0.1.2` и меньше `0.2.0`. Любой файл библиотеки CodeQL (файл с `.qll` расширением), определенный в этом пакете, будет доступен для запросов, определенных в любом пакете запросов, который включает этот пакет в блок зависимостей.

Свойство `library` указывает, что этот пакет является пакетом библиотеки и не содержит никаких запросов.

### Пакеты CodeQL для пользовательских запросов

Пользовательский пакет данных CodeQL с пользовательскими запросами и библиотеками C++ может содержать `qlpack.yml` файл:

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

где `codeql/cpp-all` имя пакета CodeQL для анализа C/C++, включенного в репозиторий CodeQL. Диапазон `^0.1.2` версий указывает, что этот пакет совместим со всеми версиями `codeql/cpp-all` , превышающими или равными `0.1.2` и меньше `0.2.0`.
`my-github-user/my-custom-libraries` — это имя пакета CodeQL с пользовательскими библиотеками CodeQL для C++. Любой файл библиотеки CodeQL (файл с `.qll` расширением), определенный в этом пакете, будет доступен для запросов в пакете `my-github-user/my-custom-queries` .

### Пакеты CodeQL для пользовательских тестов

Для пользовательских пакетов CodeQL, содержащих тестовые файлы, необходимо также включить `extractor` свойство, чтобы команда знала, `test run` как создавать тестовые базы данных. Вы также можете указать `tests` свойство.

`qlpack.yml` Следующий файл указывает, что `my-github-user/my-query-tests` зависит от `my-github-user/my-custom-queries` версии больше или равно 1.2.3 и меньше 2.0.0. Он также объявляет, что интерфейс командной строки должен использовать Java `extractor` при создании тестовых баз данных. Строка `tests: .` объявляет, что все `.ql` файлы в пакете должны выполняться в качестве тестов при `codeql test run` выполнении с параметром `--strict-test-discovery` . Как правило, тестовые пакеты не содержат `version` свойства. Это предотвращает случайное их публикацию.

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

Дополнительные сведения о выполнении тестов см. в разделе [Тестирование пользовательских запросов](/ru/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/testing-custom-queries).

## Пример CodeQL упаковывается в репозитории CodeQL

Каждый из языков в репозитории CodeQL содержит четыре основных пакета CodeQL:

* Основной пакет библиотеки для языка с схемой базы данных, используемой языком, и библиотеками CodeQL и запросами по адресу `<language>/ql/lib`

* Основной пакет запросов для языка, который включает запросы по умолчанию для языка, а также их наборы запросов в `<language>/ql/src`

* Тесты для основных языковых библиотек и запросов по адресу `<language>/ql/test`

* Примеры запросов для языка на `<language>/ql/examples`

### Пакет основной библиотеки

Ниже приведен пример `qlpack.yml` файла для [основных языковых](https://github.com/github/codeql/blob/main/cpp/ql/lib/qlpack.yml) пакетов библиотек анализа C/C++:

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

Некоторые дополнительные заметки о следующих свойствах:

* `library`: указывает, что это пакет библиотеки без исполняемых запросов. Оно предназначено только для использования в качестве зависимости для других пакетов.

* `dbscheme` и `upgrades`: эти свойства являются внутренними для CodeQL CLI и должны быть определены только в основном пакете запросов CodeQL для языка.

### Основной пакет запросов

Ниже приведен пример `qlpack.yml` файла для запросов[ анализа 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
```

Некоторые дополнительные заметки о следующих свойствах:

* `dependencies`: этот пакет запросов зависит от `codeql/cpp-all` и `codeql/suite-helpers`. Так как эти зависимости разрешаются из источника, не имеет значения, с какой версией пакета CodeQL они совместимы. Дополнительные сведения о разрешении зависимостей из источника см. в разделе ["Зависимости](/ru/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/about-codeql-workspaces#source-dependencies) источника".

* `suites`: указывает каталог, содержащий "известные" наборы запросов.

* `defaultSuiteFile`: имя файла набора запросов по умолчанию, используемого при отсутствии набора запросов.

### Тесты для основного пакета данных CodeQL

Ниже приведен пример `qlpack.yml` файла для тестов[ анализа 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: .
```

Некоторые дополнительные заметки о следующих свойствах:

* `dependencies`: этот пакет зависит от основных пакетов данных CodeQL запросов и пакетов библиотеки для C++.

* `extractor`: указывает, что все тесты будут использовать один и тот же средство извлечения C++ для создания базы данных для тестов.

* `tests`: указывает расположение тестов. В этом случае тесты находятся в корневой папке (и всех вложенных папках) пакета.

* `version`: для пакета тестов нет `version` свойства. Это предотвращает случайное публикацию тестовых пакетов.