为 Fuchsia 创建静态分析器

Shac（可伸缩封闭分析和检查）是一种统一的人体工程学工具和框架，用于编写和运行静态分析检查。该工具的源代码可在 shac 文档中找到。Shac 检查用 Starlark 编写。

设置

Shac 脚本实现位于 Fuchsia 的 //scripts/shac 目录中。

  • Shac 检查实现为采用 ctx 参数的 starlark 函数。使用此 ctx 参数访问 shac 标准库。
  • 如果您的检查针对特定语言，它应该位于某个语言特定的文件（例如：rust.star、go.star、fidl.star）中。如果特定于语言，但没有 language.star 文件，则创建一个。如果是通用函数，请使用 title.star（其中 title 是检查函数的名称）。

简单示例

以下示例是一个针对所有文件的静态分析器，它会针对字符串“http://”存在的更改创建一条非阻塞的 Gerrit 警告注释，并让用户改为使用“https://”。

def http_links(ctx):
    for path, meta in ctx.scm.affected_files().items():
        for num, line in meta.new_lines():
            matches = ctx.re.allmatches(r"(http://)\w+", line)
            if not matches:
                continue
            for match in matches:
                ctx.emit.finding(
                    message = "Avoid http:// links, prefer https://",
                    # Change to "error" if the check should block presubmit.
                    level = "warning",
                    filepath = path,
                    line = num,
                    col = match.offset + 1,
                    end_col = match.offset + 1 + len(match.groups[1]),
                    replacements = ["https://"],
                )

详细了解 shac 如何实现 emit.findings。

load("./http_links.star", "http_links")  # NEW

...

def register_all_checks():
    ...
    shac.register_check(http_links)  # NEW
    ...

高级示例

如果存在执行检查的现有工具，或者检查的逻辑很复杂（例如，不仅仅是子字符串搜索），则使用子流程会非常有用。Starlark 有意对功能进行限制，以支持在具有自有单元测试的独立工具中编写复杂的业务逻辑。

以下是在单独的 Python 脚本中实现并作为子进程运行的 JSON 格式设置工具的示例。

该检查不会重写格式有误的文件，而是会计算格式化的内容并将其传递给 ctx.emit.finding() 函数的 replacements 参数。所有格式检查都必须以这种方式实现，原因如下：

  • 检查所运行的子进程不能写入检出目录中的文件。这样可以防止行为不佳的工具进行意外更改，并确保可以安全地并行运行多项检查，而不会产生竞态条件。（请注意，文件系统沙盒仅在 Linux 上强制执行）。
  • Shac 旨在与需要向用户提出更改建议的其他自动化功能（例如在 Gerrit 中）轻松集成，而不是自动应用更改，因此为了使这些用例正常工作，必须将差异传递到 shac，而不是由子进程应用。
import json
import sys


def main():
    # Accepts one positional argument referring to the file to format.
    path = sys.args[1]
    with open(path) as f:
        original = f.read()
    # Always use 2-space indents and a trailing blank line.
    formatted = json.dumps(json.loads(original), indent=2) + "\n"
    if formatted == original:
        sys.exit(0)
    else:
        print(json.dumps(doc, indent=2) + "\n")
        sys.exit(1)


if __name__ == "__main__":
    main()

load("./common.star", "FORMATTER_MSG", "cipd_platform_name", "get_fuchsia_dir", "os_exec")

def json_format(ctx):
    # Launch processes in parallel.
    procs = {}
    for f in ctx.scm.affected_files():
        if not f.endswith(".json"):
            continue
        # Call fuchsia-specific `os_exec` function instead of
        # `ctx.os.exec()` to ensure proper executable resolution.
        # `os_exec` starts the subprocess but does not block.
        procs[f] = os_exec(ctx, [
            "%s/prebuilt/third_party/python3/%s/bin/python3" % (
                get_fuchsia_dir(ctx),
                cipd_platform_name(ctx),
            ),
            "scripts/shac/json_format.py",
            f,
        ])

    for f, proc in procs.items():
        # wait() blocks until the process completes.
        res = proc.wait()
        if proc.retcode != 0:
            ctx.emit.finding(
                level = "error",
                filepath = f,
                # FORMATTER_MSG is the standard message for formatters
                # in fuchsia.git.
                message = FORMATTER_MSG,
                # json_format.py prints the formatted file contents to stdout.
                # Passing it to `replacements` is necessary for shac to know
                # how to apply the fix.
                replacements = [res.stdout],
            )

# TODO: call this somewhere
shac.register_check(shac.check(
    json_format,
    # Mark the check as a formatter. Only checks with `formatter = True`
    # get run by `fx format-code`.
    formatter = True,
))
性能优化

一些格式化程序具有内置支持，可以同时验证多个文件的格式，这通常在内部并行处理，因此比启动单独的子进程来检查每个文件要快得多。在这种情况下，您可以在“检查”模式下对所有文件运行一次格式化程序，以获取格式错误的文件列表，然后仅遍历格式有误的文件以获取格式化的结果（而不是遍历所有文件）。

示例：对于 rustfmt，请先运行 rustfmt --check --files-with-diff <all rust files> 以获取格式有误文件的列表，然后对每个文件分别运行 rustfmt 以获取格式化的结果。

如果格式化程序没有将格式化结果输出到 stdout 的试运行模式：格式化程序子进程将无法写入检出。不过，有些格式化程序会无条件地写入文件。在这种情况下，您需要将每个文件复制到一个 tempdir 中，子进程可以向 tempdir 中写入数据，设置临时文件的格式并报告其内容，示例请参阅构建程序。

默认情况下，如果子进程生成非零返回代码，os_exec 会引发不可恢复的错误。如果预期返回非零返回代码，您可以使用 ok_retcodes 参数，例如，如果格式化程序在文件格式未设置时生成返回代码 1，则 ok_retcodes = [0, 1] 可能适合使用。

在本地运行检查

在本地检查开发期间，建议您直接通过 fx host-tool shac check <file> 运行 shac 以测试检查。让我们创建一个场景，用于测试上述 http_links 检查：

  1. 查找当前违反检查的文件，或创建新文件（如果不存在），例如：echo "http://example.com" > temp.txt
  2. fx host-tool shac check --only http_links temp.txt
    • 此操作应该会失败，并显示突出显示“http://”的文件内容
    • --only 会导致 shac 仅运行 http_links 检查（不包括其他检查），因为在这种情况下，我们只关注测试 http_links，而不关注其他检查的结果
  3. fx host-tool shac fix --only http_links temp.txt 应将 http:// 更改为 https://
  4. fx host-tool shac check --only http_links temp.txt现在应该通过
  5. fx host-tool shac check --only http_links --all
    • 对树中的所有文件（//shac.textproto 中被 git-ignored 或被忽略的文件除外）运行，而不仅仅是对已更改的文件运行
    • 如果此操作失败并出现错误，您就需要在同一次提交中或单独提交中修正违规文件中这些错误（最好有 10 个以上需要修正的文件），然后再进行检查。
      • 或者，将检查设为非阻塞，修正错误，然后将其切换为阻塞
    • 如果您的检查发出了警告，请注意有多少个警告。如果存在非常大的数量（超过 100 秒），则会导致许多嘈杂的 Gerrit 注释，并且可能会对其他贡献者造成干扰。建议您事先进行批量修正，以缩小检查范围或重新考虑检查的实用性。
  6. 最后，将检查上传到 Gerrit，运行预提交，以零失败为目标检查失败情况。（提交前的行为与运行 fx host-tool shac check --all 的行为相同）

建议您记录您的检查是否选择启用（不在提交前运行）或有不明显的退出机制。所有文档都应添加到 //docs/development/source_code/presubmit_checks.md