Skip to main content
Мы публикуем частые обновления нашей документации, и перевод этой страницы может все еще выполняться. Актуальные сведения см. в документации на английском языке.
All products
Безопасность кода

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

В этой статье

CodeQL CLI можно использовать для предварительного просмотра файлов справки по запросам в качестве Markdown и проверки их допустимости.

GitHub CodeQL лицензируется для каждого пользователя после установки. CodeQL можно использовать только для определенных задач с ограничениями лицензии. Дополнительные сведения см. в разделе Сведения о CodeQL CLI.

Если у вас есть лицензия на GitHub Advanced Security, вы можете использовать CodeQL для автоматического анализа, непрерывной интеграции и непрерывной поставки. Дополнительные сведения см. в разделе Сведения о GitHub Advanced Security.

Примечание: Эта статья была перенесена с веб-сайта документации CodeQL в январе 2023 г.

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

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

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

CodeQL CLI включает команду для проверки справки по запросу и отображения содержимого в виде Markdown, что позволяет легко просматривать содержимое в интегрированной среде разработки. Используйте команду , чтобы проверить файлы справки запроса, прежде чем отправлять их в репозиторий CodeQL или предоставлять к ним доступ другим пользователям. Начиная с CodeQL CLI версии 2.7.1, вы также можете включить справку по запросам, отрисованную с помощью Markdown, в ФАЙЛЫ SARIF, созданные во время анализа CodeQL, чтобы справка по запросу отображалась в пользовательском интерфейсе сканирования кода. Дополнительные сведения см. в разделе Анализ баз данных с помощью CodeQL CLI.

Предварительные требования

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

Необходимо указать --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 параметр в команду . Дополнительные сведения см. в разделе создание справки по запросу.

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