Skip to main content

Тестирование файлов справки по запросу

You can use the CodeQL CLI to preview your query help files as Markdown and ensure they are valid.

Кто эту функцию можно использовать?

GitHub CodeQL is licensed on a per-user basis upon installation. You can use CodeQL only for certain tasks under the license restrictions. For more information, see "About the CodeQL CLI."

If you have a GitHub Advanced Security license, you can use CodeQL for automated analysis, continuous integration, and continuous delivery. For more information, see "About GitHub Advanced Security."

Сведения о файлах справки по запросу тестирования

Тестируйте файлы справки по запросу, отрисовав их как Markdown, чтобы убедиться, что они действительны перед отправкой в репозиторий CodeQL или с их помощью в сканировании кода.

Справка по запросу — это документация, которая сопровождает запрос, чтобы объяснить, как работает запрос, а также предоставить сведения о потенциальной проблеме, которую идентифицирует запрос. Рекомендуется написать справку по запросу для всех новых запросов. Дополнительные сведения см. в статье "Участие в CodeQL в репозитории CodeQL.

CodeQL CLI включает команду для тестирования справки по запросу и отрисовки содержимого в виде markdown, чтобы можно было легко просмотреть содержимое в интегрированной среде разработки. Используйте команду для проверки файлов справки по запросу перед отправкой их в репозиторий CodeQL или совместного использования с другими пользователями. Начиная с CodeQL CLI 2.7.1, вы также можете включить справку по запросу markdown, отображаемую в файлах SARIF, созданных во время анализа CodeQL для отображения справки по запросу в пользовательском интерфейсе сканирования кода. Дополнительные сведения см. в разделе «AUTOTITLE».

Необходимые компоненты

  • Файл справки запроса (.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 параметр в команду. Дополнительные сведения см. в разделе «AUTOTITLE».

Дополнительные материалы