Сведения о файлах справки по запросу тестирования
Тестируйте файлы справки по запросу, отрисовав их как Markdown, чтобы убедиться, что они действительны перед отправкой в репозиторий CodeQL или с их помощью в сканировании кода.
Справка по запросу — это документация, которая сопровождает запрос, чтобы объяснить, как работает запрос, а также предоставить сведения о потенциальной проблеме, которую идентифицирует запрос. Рекомендуется написать справку по запросу для всех новых запросов. Дополнительные сведения см. в статье "Участие в CodeQL в репозитории CodeQL.
CodeQL CLI включает команду для тестирования справки по запросу и отрисовки содержимого в виде markdown, чтобы можно было легко просмотреть содержимое в интегрированной среде разработки. Используйте команду для проверки файлов справки по запросу перед отправкой их в репозиторий CodeQL или совместного использования с другими пользователями. Начиная с CodeQL CLI 2.7.1, вы также можете включить справку по запросу markdown, отображаемую в файлах SARIF, созданных во время анализа CodeQL для отображения справки по запросу в пользовательском интерфейсе сканирования кода. Дополнительные сведения см. в разделе Анализ кода с помощью запросов 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
содержащих файлы или наборы запросов, определяющие один или несколько.qhelp
файлов, необходимо указать--output
каталог. Имена файлов в выходном.qhelp
каталоге будут производными от имен файлов. - Для одного
.qhelp
или.ql
файлов можно указать--output
параметр. Если вы не указываете выходной путь, функция справки по отрисованному запросу записывается вstdout
.
Полные сведения обо всех параметрах, которые можно использовать при тестировании файлов справки запросов, см. в разделе "создание справки по запросу".
Результаты
При выполнении команды CodeQL пытается отобразить каждый .qhelp
файл с сопутствующим .ql
файлом. Для отдельных файлов отрисованное содержимое будет напечатано stdout
, если параметр не указан --output
. Во всех других случаях использования отрисованное содержимое сохраняется в указанном выходном пути.
По умолчанию CodeQL CLI выводит предупреждение, если:
- Любая справка по запросу является недопустимой, а также описание недопустимых элементов справки запроса
- Все
.qhelp
файлы, указанные в команде, не имеют того же базового имени, что и сопровождающий.ql
файл. - Все
.ql
файлы, указанные в команде, не имеют того же базового имени, что и сопровождающий.qhelp
файл.
Вы можете сообщить CodeQL CLI об обработке этих предупреждений, включив --warnings
параметр в команду. Дополнительные сведения см. в разделе создание справки по запросу.