# CodeQL クエリパック参照

CodeQL パックの互換性、内容、および構造について理解します。

## CodeQL パックの互換性

クエリ パックが発行されると、分析速度を向上させるために、その中のすべてのクエリのプリコンパイル済み表現が含まれます。 ただし、分析を実行する CodeQL のバージョンが、 `codeql pack publish`実行したバージョンより 6 か月以上新しい場合は、分析中にソースからクエリをコンパイルする必要があり、プロセスが大幅に遅くなる可能性があります。

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 を使用してパックを発行することをお勧めします。 さらに、更新された CodeQL バージョンを 6 か月ごとに使用して、新しいバージョンのパックを発行する必要があります。

バンドルされている 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`

* 発行されるすべてのパックで必須。
* [SemVer v2.0.0 仕様](https://semver.org/spec/v2.0.0.html)に準拠する必要がある、この CodeQL パックのセマンティック バージョンを定義します。 例えば次が挙げられます。

  ```yaml
  version: 0.0.0
  ```

#### `dataExtensions`

* モデル パックで必須。
* クエリ パックまたはライブラリ パックのルートを基準にしてデータ拡張ファイルが配置される場所を指定する glob パターンの一覧を取得します。

#### `dependencies`

* 他のパックに対する CodeQL パッケージの依存関係を定義するクエリとライブラリ パックで必須。 モデル パックでは依存関係を定義できず、代わりに `extensionTargets` を使用できます。
* パック参照から、このパックと互換性のあるセマンティック バージョン範囲へのマップを定義します。 CodeQL CLI バージョン v2.6.0 以降でサポートされています。 例えば次が挙げられます。

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

  不明な場合、または使用するバージョンが重要でない場合は、この依存関係の任意のバージョンがこのパックと互換性があることを示す `"*"` を使用できます 。 実際には、これは通常、公開されている依存関係の最も高いバージョンに解決されます。

  特別なバージョンのプレースホルダーがあります。これは、`${workspace}`この CodeQL パックが、同じワークスペース内にある依存関係のバージョンによって異なることを示します。 詳しくは、「[CodeQL ワークスペースについて](/ja/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 バージョン v2.6.0 以降でサポートされています。
  `defaultSuiteFile` または `defaultSuite` のいずれか 1 つのみを定義できます。 例えば次が挙げられます。

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

#### `defaultSuite`

* 実行する一連の既定のクエリをエクスポートするパックで必須。
* このパックが `codeql database analyze` コマンドに渡されたときに既定で実行されるすべてのクエリを含むインライン クエリ スイートを定義します。 CLI バージョン v2.6.0 以降でサポートされています。
  `defaultSuiteFile` または `defaultSuite` のいずれか 1 つのみを定義できます。 例えば次が挙げられます。

  ```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 パックは一覧に含まれます。

  * マイナス記号なしで一覧表示されているグループの少なくとも 1 つに属している (マイナス記号なしでリストされているグループがない場合、この条件は自動的に満たされます)。
  * マイナス記号が付いた一覧表示されているどのグループにも属していません。

#### `library`

* ライブラリ パックで必須。
* このパックがライブラリ パックであるかどうかを示すブール値を定義します。 ライブラリ パックにはクエリは含まれず、コンパイルされません。 クエリ パックでは、このフィールドを無視するか、明示的に `false` に設定できます。 例えば次が挙げられます。

  ```yaml
  library: true
  ```

#### `suites`

* クエリ スイートを定義するパックの場合は省略可能。 これにより、ユーザーは完全なパスを指定せずに、パック名を指定することで、指定したディレクトリに保存されているクエリ スイートを実行できます。
* 現在、CodeQL CLI バンドルに含まれている標準クエリ パックでのみサポートされています。
* このオプションは、CodeQL コンテナ レジストリからダウンロードされた GitHub パックではサポートされていません。

#### `tests`

* CodeQL テストを含むパックの場合は省略可能。 テストが含まれていないパックの場合は無視されます。
* テストを含むパック内のディレクトリへのパスを定義します。これは、パック ディレクトリを基準に定義されます。 パック全体を指定するには、`.` を使用します。
  `test run` オプションを指定して `--strict-test-discovery` を実行すると、このディレクトリ内のすべてのクエリがテストとして実行されます。
  `queries` または `qlpack` 命令を使用して特定のパック内のすべてのクエリを要求するクエリ スイート定義では、これらのクエリは無視されます。 このプロパティがない場合、`.` と見なされます。 例えば次が挙げられます。

  ```yaml
  tests: .
  ```

#### `extractor`

* CodeQL テストを含むすべてのパックで必須。
* パック内の CodeQL テストを実行するときに使用する CodeQL 言語抽出子を定義します。 クエリのテストについて詳しくは、「[カスタム クエリのテスト](/ja/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 パックが発行されるアカウントのパッケージ セクションでパッケージ検索ページに表示されるメタデータを定義します。 許可されているライセンスの一覧については、SPDX 仕様の [SPDX ライセンス リスト](https://spdx.org/licenses/)を参照してください。 例えば次が挙げられます。

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

* コア言語パックでのみ必須。
* この CodeQL 言語用に記述されたすべてのライブラリとクエリの[データベース スキーマ](https://codeql.github.com/docs/codeql-overview/codeql-glossary/#codeql-database-schema)へのパスを定義します (次の例を参照)。 例えば次が挙げられます。

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

#### `upgrades`

* コア言語パックでのみ必須。
* データベース アップグレード スクリプトを含むパック内のディレクトリへのパスを定義します。これは、パック ディレクトリを基準に定義されます。 データベースのアップグレードは、別のバージョンの CodeQL CLI で作成されたデータベースと CLI の現在のバージョンとの互換性を確保するために内部的に使用されます。 例えば次が挙げられます。

  ```yaml
  upgrades: .
  ```

#### `warnOnImplicitThis`

* このフィールドは省略可能です。
  `false` プロパティが定義されていない場合、既定値は `warnOnImplicitThis` に設定されます。
* 暗黙的な `this` 呼び出しレシーバー (つまり、明示的なレシーバーなし) を指定するメンバー述語呼び出しに関する警告をコンパイラが出力するかどうかを指定するブール値を定義します。 CodeQL CLI v2.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 ワークスペースおよびソースからの依存関係の解決に関する詳細については、「[AUTOTITLE](/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 パック

クエリやテストを含まないカスタム C++ ライブラリを含むカスタム CodeQL パックには、`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 パック

カスタム C++ クエリとライブラリを含むカスタム CodeQL パックには、`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` は、C++ 用のカスタム CodeQL ライブラリを含む CodeQL パックの名前です。 このパックで定義されている CodeQL ライブラリ ファイル (拡張子が `.qll` のファイル) は、`my-github-user/my-custom-queries` パック内のクエリで使用できます。

### カスタム テスト用の CodeQL パック

テスト ファイルを含むカスタム CodeQL パックの場合、`extractor` コマンドでテスト データベースの作成方法を認識できるように、`test run` プロパティも含める必要があります。
`tests` プロパティを指定することもできます。

次の `qlpack.yml` ファイルは、`my-github-user/my-query-tests` が 1.2.3 以上で 2.0.0 未満のバージョンの `my-github-user/my-custom-queries` に依存していることを示しています。 また、テスト データベースの作成時に CLI で Java `extractor` を使用する必要があることを宣言します。 `tests: .` 行では、`--strict-test-discovery` オプションを指定して `codeql test run` を実行する際に、パック内のすべての `.ql` ファイルをテストとして実行する必要があることを宣言します。 通常、テスト パックに `version` プロパティは含まれません。 これにより、それらが誤って発行されるのを防ぐことができます。

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

テスト実行の詳細については、「[カスタム クエリのテスト](/ja/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/testing-custom-queries)」を参照してください。

## CodeQLのリポジトリにあるCodeQLパックの例

CodeQL リポジトリの各言語には、次の 4 つの主要な 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) ファイルの例を次に示します。
```

```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` コア クエリ パックの [](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 パックのバージョンは関係ありません。 ソースからの依存関係の解決について詳しくは、「[ソース依存関係](/ja/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/about-codeql-workspaces#source-dependencies)」を参照してください。

* `suites`: "既知" のクエリ スイートを含むディレクトリを示します。

* `defaultSuiteFile`: クエリ スイートが指定されていない場合に使用される既定のクエリ スイート ファイルの名前。

### コア CodeQL パックのテスト

```
          `qlpack.yml` コア テスト パックの [](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`: このパックは、C++ のコア CodeQL クエリ パックとライブラリ パックに依存します。

* `extractor`: これは、すべてのテストで同じ C++ 抽出子を使用してテスト用のデータベースを作成することを指定します。

* `tests`: これは、テストの場所を指定します。 この場合、テストは、パックのルート フォルダー (およびすべてのサブフォルダー) 内にあります。

* `version`: テスト パックの `version` プロパティはありません。 これにより、テスト パックが誤って発行されるのを防ぐことができます。