クエリ ヘルプ ファイルのテストについて
クエリ ヘルプ ファイルをテストするには、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 に示すことができます。 詳しくは、「クエリ ヘルプを生成する」を参照してください。