The Wayback Machine - https://web.archive.org/web/20230130221853/https://docs.github.com/ru/code-security/code-scanning/using-the-codeql-cli/testing-query-help-files
Skip to main content
We publish frequent updates to our documentation, and translation of this page may still be in progress. For the most current information, please visit the English documentation.
 

 

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

In this article

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

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

Если у вас есть учетная запись GitHub Enterprise и лицензия на 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 параметр в команду . Дополнительные сведения см. в справочной документации по созданию запросов.

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