为 Fuchsia 创建静态分析器

Shac(可伸缩的密封分析和检查)是一款统一且符合人体工学的工具和框架,用于编写和运行静态分析检查。您可以在 shac 文档中找到该工具的源代码。Shac 检查是用 Starlark 编写的。

设置

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

  • SHAC 检查是作为接受 ctx 参数的 Starlark 函数实现的。使用此 ctx 参数访问 shac 标准库。
  • 如果您的检查因语言而异,则应将其添加到特定于语言的文件(例如 rust.stargo.starfidl.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 的实现。

请注意,Shac 不会自动发现检查。为了运行检查,必须将检查函数传递给 //scripts/shac/main.star 中的 shac.register_check()

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

...

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

在已包含其他检查的文件中实现新检查时,您或许可以在该文件中注册新检查。例如,//scripts/shac/fidl.star 有一个从 //scripts/shac/main.star 调用的 register_fidl_checks() 函数。向 fidl.star 添加新的 FIDL 检查,并在同一文件中的 register_fidl_checks() 函数中注册这些检查。

高级示例

如果有现有工具可执行检查,或者检查逻辑较为复杂(例如不仅仅是子字符串搜索),则使用子进程会很有用。Starlark 的功能是故意受限的,目的是鼓励您在具有自己的单元测试的独立工具中编写复杂的业务逻辑。

以下是一个 JSON 格式化程序示例,该格式化程序在单独的 Python 脚本中实现,并作为子进程运行。

该检查会计算格式化的内容,并将其传递给 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,子进程可以向该目录写入、设置临时文件格式并报告其内容,如需查看示例,请参阅 buildifier

默认情况下,如果子进程生成非零返回代码,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
    • 对树中的所有文件(git 忽略的文件或 //shac.textproto 中忽略的文件除外)运行,而不仅仅是更改后的文件
    • 如果此操作失败并出现错误,您需要在提交检查之前,在同一提交中或单独的提交中修复相应文件中的错误(如果要修复的文件大约超过 10 个,则最好在单独的提交中修复)。
      • 或者,将检查设为非阻塞,修复错误,然后将其切换为阻塞
    • 如果您的检查发出了警告,请记下警告数量。如果数量非常大(超过 100 个),则会导致大量噪声 Gerrit 评论,并可能会干扰其他贡献者。请考虑事先进行批量修复、缩小检查范围或重新考虑检查的实用性。
  6. 最后,将检查上传到 Gerrit,运行预提交检查,检查失败情况,以实现 0 失败为目标。(提交前的行为与运行 fx host-tool shac check --all 相同)

如果您的检查是用户选择启用(不会在提交前运行)或具有不明显的停用机制,建议您记录该检查。所有文档都应添加到 //docs/development/source_code/presubmit_checks.md