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

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

В этой статье

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

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

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

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