cargo-checkmate

执行一系列有用的检查。 cargo-checkmate 确保您的项目可以构建，测试通过，格式良好，没有已知漏洞的依赖项等。

其理念是您可以在大多数 crates 上直接运行它，无需配置，以尽可能多地捕获问题（低误报率）。不配置的理由是，无论个人开发者的配置如何，checkmate 的失败应该对所有开发者（对于 cargo-checkmate 的给定版本）都是相同的。

如何使用它

$ cargo install cargo-checkmate
...

$ cd /path/to/your/crate

$ cargo checkmate

running 7 cargo-checkmate phases
cargo-checkmate check... ok.
cargo-checkmate format... ok.
cargo-checkmate clippy... ok.
cargo-checkmate build... ok.
cargo-checkmate test... ok.
cargo-checkmate doc... ok.
cargo-checkmate audit... ok.

cargo-checkmate result: ok. 7 passed; 0 failed

git 钩子

如果您的 crate 在 git 仓库中，您可以通过在 pre-commit git 钩子中运行它来验证每个提交是否遵循 cargo checkmate 检查。您可以安装一个预先捆绑的 git 钩子，它正好做这件事。

$ cargo checkmate git-hook install
cargo-checkmate git-hook installed: ".git/hooks/pre-commit"

现在提交被检查了

$ touch foo
$ git add foo
$ git commit -m 'Demo cargo checkmate git-hook usage.'

cargo checkmate git-hook:
Removing prior log directory: ./target/cargo-checkmate/logs

running 6 cargo-checkmate phases
cargo-checkmate check... ok.
cargo-checkmate format... ok.
cargo-checkmate build... ok.
cargo-checkmate test... ok.
cargo-checkmate doc... ok.
cargo-checkmate audit... ok.

cargo-checkmate result: ok. 6 passed; 0 failed
[master 6e3230a] Demo cargo checkmate git-hook usage.
 1 file changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 src/foo

如果您想故意跳过提交的检查，git 提供了 git commit --no-verify 标志。如果您改变了主意，您也可以取消安装。

$ cargo checkmate git-hook uninstall
cargo-checkmate git-hook uninstalled: ".git/hooks/pre-commit"

安装和取消安装都尽量小心，以免破坏任何未识别的 pre-commit 钩子，以防您已经有一个自定义的钩子。

$ cargo checkmate git-hook install
cargo-checkmate git-hook installed: ".git/hooks/pre-commit"

$ cargo checkmate git-hook install
cargo-checkmate git-hook already installed: ".git/hooks/pre-commit"

$ echo 'blah' > .git/hooks/pre-commit

$ cargo checkmate git-hook uninstall
cargo-checkmate unrecognized git-hook: ".git/hooks/pre-commit"
Error: Custom { kind: Other, error: "Unrecongized git-hook: \".git/hooks/pre-commit\"" }

$ cargo checkmate git-hook install
cargo-checkmate unrecognized git-hook: ".git/hooks/pre-commit"
Error: Custom { kind: Other, error: "Unrecongized git-hook: \".git/hooks/pre-commit\"" }

GitHub CI

如果您使用 GitHub，您可以为每个 push 和 pull_request 事件安装一个 GitHub Action，它会运行 cargo-checkmate。

$ cargo checkmate github-ci install
cargo-checkmate GitHub CI installed: "/path/to/your/crate/.github/workflows/cargo-checkmate.yaml"

您必须单独将此命令提交到您的存储库。

安装/卸载行为与git-hook子命令的逻辑相同，注意不要删除或覆盖意外的文件内容。

日志

每个检查阶段将stdout和stderr记录到./target/cargo-checkmate/logs

$ cat ./target/cargo-checkmate/logs/doc.stderr
 Documenting cargo-checkmate v0.1.2 (/home/user/hack/cargo-checkmate)
    Finished dev [unoptimized + debuginfo] target(s) in 1.67s

每次运行时，先删除任何现有的日志，并将此事实报告出来

$ cargo checkmate
Removing prior log directory: ./target/cargo-checkmate/logs

running 6 cargo-checkmate phases
cargo-checkmate check... ok.
cargo-checkmate format... ok.
cargo-checkmate build... ok.
cargo-checkmate test... ok.
cargo-checkmate doc... ok.
cargo-checkmate audit... ok.

cargo-checkmate result: ok. 6 passed; 0 failed

失败

如果任何阶段失败，将自动显示stdout/stderr日志

$ # Introduce a poorly formatted unit test:
$ echo '#[test] fn bad_format() {}' >> src/main.rs
$ cargo checkmate
Removing prior log directory: ./target/cargo-checkmate/logs

running 6 cargo-checkmate phases
cargo-checkmate check... ok.
cargo-checkmate format... FAILED.
cargo-checkmate build... ok.
cargo-checkmate test... ok.
cargo-checkmate doc... ok.
cargo-checkmate audit... ok.

failures:

---- cargo-checkmate format ----
+ ./target/cargo-checkmate/logs/format.stdout:
| Diff in /home/user/hack/cargo-checkmate/src/main.rs at line 17:
|      let check = Check::parse_args(std::env::args())?;
|      check.execute()
|  }
| -#[test] fn bad_format() {}
| +#[test]
| +fn bad_format() {}
|

cargo-checkmate result: FAILED. 5 passed; 1 failed

审计

审计新鲜度

命令cargo audit总是获取需要网络访问和延迟的advisory数据库。作为一个优化，如果以下条件成立，cargo-checkmate将跳过cargo audit

• Cargo.lock未修改，并且
• 上次成功运行cargo audit的时间戳小于三小时。

这优化了cargo-checkmate的使用，特别是对于git hook，假设开发者在几个小时内在提交很多修订。

忽略漏洞披露

有时你的crate的间接依赖项有漏洞披露，这些披露你已经知道，无法通过简单的cargo update解决，并且对你的crate的用户影响最小。在这种情况下，你可以指示cargo audit忽略它们，这样就不会阻塞你在持续集成流程中成功完成cargo checkmate。

为此，为你的项目配置cargo audit以忽略特定问题。在注释中解释为什么它们被忽略是良好的实践。

配置文件位于你的crate项目目录中的.cargo/audit.toml。目前，cargo checkmate本身忽略了两个错误

[advisories]
ignore = [
    # `time` localtime_r segfault
    # This is ignored without a clear understanding of the impact on `cargo-checkmate`!
    "RUSTSEC-2020-0071",

    # `chrono` localtime_r segfault
    # This is ignored without a clear understanding of the impact on `cargo-checkmate`!
    "RUSTSEC-2020-0159",
]