クエリ ヘルプ ファイルのテストについて
クエリ ヘルプ ファイルをテストするには、CodeQL リポジトリにアップロードする前、またはコード スキャンで使用する前に、それらを Markdown としてレンダリングして有効であることを確かめます。
クエリ ヘルプは、クエリで特定される潜在的な問題に関する情報を提供するだけでなく、クエリの動作を説明するクエリに付随するドキュメントです。 すべての新しいクエリのクエリ ヘルプを記述することをお勧めします。 詳しくは、CodeQL リポジトリの「CodeQL への投稿」を参照してください。
CodeQL CLI には、クエリ ヘルプをテストし、コンテンツを Markdown としてレンダリングするコマンドが含まれているため、IDE でコンテンツを簡単にプレビューできます。 コマンドを使用して、CodeQL リポジトリにアップロードしたり、他のユーザーと共有したりする前に、クエリ ヘルプ ファイルを検証します。 CodeQL CLI 2.7.1 以降では、CodeQL 分析中に生成された SARIF ファイルに Markdown レンダリング クエリ ヘルプを含めて、クエリ ヘルプをコード スキャン UI に表示することもできます。 詳しくは、「CodeQL クエリによるコード分析」を参照してください。
前提条件
- クエリ ヘルプ (
.qhelp
) ファイルには、同じベース名の添付のクエリ (.ql
) ファイルが必要です。 - クエリ ヘルプ ファイルは、クエリ ヘルプ ドキュメントの標準の構造とスタイルに従う必要があります。 詳しくは、CodeQL リポジトリの「クエリ ヘルプ スタイル ガイド」を参照してください。
実行中 codeql generate query-help
次のコマンドを実行して、クエリ ヘルプ ファイルをテストできます。
codeql generate query-help <qhelp|query|dir|suite> --format=<format> [--output=<dir|file>]
このコマンドの <qhelp|query|dir|suite>
は、.qhelp
ファイルへのパス、.ql
ファイルへのパス、クエリとクエリ ヘルプ ファイルを含むディレクトリへのパス、またはクエリ スイートへのパスである必要があります。
クエリ ヘルプのレンダリング方法を定義する --format
オプションを指定する必要があります。 現時点では、クエリ ヘルプを Markdown としてレンダリングするために markdown
を指定する必要があります。
--output
オプションでは、レンダリングされたクエリ ヘルプを保存するファイル パスを定義します。
.qhelp
ファイルを含むディレクトリあるいは 1 つまたは複数の.qhelp
ファイルを定義するクエリ スイートの場合は、--output
ディレクトリを指定する必要があります。 出力ディレクトリ内のファイル名は、.qhelp
ファイル名から派生します。- 単一の
.qhelp
または.ql
ファイルの場合は、--output
オプションを指定できます。 出力パスを指定しない場合、レンダリングされたクエリ ヘルプはstdout
に書き込まれます。
クエリ ヘルプ ファイルのテスト時に使うことができるすべてのオプションについて詳しくは、「クエリ ヘルプを生成する」をご覧ください。
結果
コマンドを実行すると、CodeQL では、添付の .ql
ファイルを含む各 .qhelp
ファイルのレンダリングが試みられます。 単一のファイルでは、--output
オプションを指定しない場合、レンダリングされたコンテンツが stdout
に出力されます。 その他のすべてのユース ケースでは、レンダリングされたコンテンツは指定された出力パスに保存されます。
既定では、CodeQL CLI では次の場合に警告メッセージが出力されます。
- クエリ ヘルプのいずれかが無効で、無効なクエリ ヘルプ要素の説明が含まれている
- コマンドで指定された
.qhelp
ファイルに、添付の.ql
ファイルと同じベース名がない - コマンドで指定された
.ql
ファイルに、添付の.qhelp
ファイルと同じベース名がない
コマンドに --warnings
オプションを含めることで、これらの警告の処理方法を CodeQL CLI に示すことができます。 詳しくは、「クエリ ヘルプを生成する」を参照してください。