Skip to main content

クエリ ヘルプ ファイルのテスト

CodeQL CLI を使用して、クエリ ヘルプ ファイルを Markdown としてプレビューし、有効であることを確かめることができます。

この機能を使用できるユーザーについて

CodeQL は、次の種類のリポジトリで使用できます:

クエリ ヘルプ ファイルのテストについて

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

参考資料