关于查询帮助文件
通过将查询帮助文件呈现为 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”。