Skip to main content

测试查询帮助文件

可以使用 CodeQL CLI 以 Markdown 的形式预览查询帮助文件,并确保它们有效。

谁可以使用此功能?

GitHub CodeQL 在安装后按用户授权。 根据许可证限制,只能将 CodeQL 用于某些任务。 有关详细信息,请参阅“关于 CodeQL CLI”。

如果你有 GitHub Advanced Security 许可证,则可以使用 CodeQL 进行自动分析、持续集成和持续交付。 有关详细信息,请参阅“关于 GitHub 高级安全性”。

关于查询帮助文件

通过将查询帮助文件呈现为 Markdown 来对其进行测试,以先确保其有效,然后再将其上传到 CodeQL 存储库或在代码扫描中使用它们。

查询帮助是一个文档,它附带了一个查询来说明查询的工作原理,并提供有关查询识别的潜在问题的信息。 建议为所有新查询编写查询帮助。 有关详细信息,请参阅 CodeQL 存储库中的参与 CodeQL

CodeQL CLI 包含一个命令,用于测试查询帮助并将内容呈现为 markdown,使用户可以在 IDE 中轻松预览内容。 先使用该命令验证查询帮助文件,再将这些文件上传到 CodeQL 存储库或与其他用户共享。 从 CodeQL CLI 2.7.1 开始,还可以在 CodeQL 分析期间生成的 SARIF 文件中包含呈现为 markdown 的查询帮助,以便查询帮助可以在代码扫描 UI 中显示。 有关详细信息,请参阅“使用 CodeQL 查询分析代码”。

先决条件

  • 查询帮助 (.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

有关测试查询帮助文件时可使用的所有选项的完整详细信息,请参阅“generate query-help”。

结果

运行命令时,CodeQL 会尝试呈现每个具有随附 .ql 文件的 .qhelp 文件。 对于单个文件,如果未指定 --output 选项,则将在 stdout 中显示呈现的内容。 对于所有其他用例,呈现的内容将保存到指定的输出路径。

默认情况下,CodeQL CLI 将在以下情况下显示警告消息:

  • 任何查询帮助都无效,无效查询帮助元素的说明也是如此
  • 命令中指定的任何 .qhelp 文件都不具有与随附 .ql 文件相同的基名称
  • 命令中指定的任何 .ql 文件都不具有与随附 .qhelp 文件相同的基名称

可以通过在命令中包含 --warnings 选项来告诉 CodeQL CLI 如何处理这些警告。 有关详细信息,请参阅“generate query-help”。

延伸阅读