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

В этой статье

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

Необходимо указать параметр, определяющий --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».

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