rust-quality-gate

Rust 质量门禁协议

何时调用

在以下情况下调用此协议：

• 完成任何实现任务且代码更改已准备好提交时
• 用户要求“检查质量”“运行测试”“运行 clippy”“是否可以发布”或“验证”时
• 创建拉取请求或合并到 main 之前
• 修改共享库 crate（trusty-common、trusty-mcp-core、trusty-embedder、trusty-symgraph）之后
• rust-qa Agent 交付工作成果之后

三道门禁的执行顺序

严格按照此顺序运行门禁。首次失败即停止，不要继续下一道门禁。

门禁 1：格式检查（最快——始终先运行）

cargo fmt --check

通过：无输出，退出代码为 0。

失败：列出存在格式差异的文件。使用以下命令修复：

cargo fmt

然后重新运行 cargo fmt --check，确认格式无误。

为何先运行：格式问题很容易修复。先检查格式，可避免在未格式化的代码上浪费运行 clippy 和测试的时间。

门禁 2：Clippy lint 门禁

cargo clippy --workspace --all-targets -- -D warnings

通过：未输出警告，退出代码为 0。

失败：出现一条或多条 error[clippy::] 行。修复编译器报告的每条警告。常见模式：

# Check a single crate faster during iteration
cargo clippy -p trusty-search -- -D warnings

# Check with a specific feature enabled
cargo clippy -p trusty-common --features axum-server -- -D warnings

open-mpm 例外：open-mpm 在 HEAD 中有 142 个既存的 clippy 错误（单独跟踪）。这些错误不会阻碍其他工作。运行整个工作区的 clippy 时，如果 open-mpm 失败，请确认失败是否仅限于 open-mpm：

# Run clippy on everything except open-mpm to confirm other crates are clean
cargo clippy --workspace --all-targets -- -D warnings 2>&1 | grep -v "open-mpm"

如果所有错误都在 open-mpm 中，对于非 open-mpm 工作，可视为通过此门禁。

门禁 3：测试门禁

单个 crate（快速——迭代时使用）：

cargo test -p <crate>

整个工作区（提交前必需）：

cargo test --workspace

包含被忽略的集成测试（完整验证）：

cargo test -p <crate> -- --include-ignored
# or workspace-wide:
cargo test --workspace -- --include-ignored

Crate 名称与目录名称

Cargo 的 -p 标志使用 Cargo.toml 中的 name 字段，而不是目录名称。例外情况：

目录	Cargo 标志
crates/trusty-git-analytics/	-p tga
crates/open-mpm/	-p open-mpm

其他所有 crate：目录名称 = crate 名称（例如，crates/trusty-search/ → -p trusty-search）。

读取测试输出

Cargo 测试输出以摘要行结尾：

test result: ok. 42 passed; 0 failed; 3 ignored; 0 measured; 0 filtered out

字段	含义
passed	已运行且成功的测试
failed	已运行但失败的测试——必须为零
ignored	标记为 #[ignore] 的测试——默认跳过（ONNX/集成测试）
measured	基准测试结果（仅 bench 模式）

#[ignore] 测试：这些是耗时的、基于 ONNX 的测试，或依赖环境的集成测试。默认门禁会有意跳过这些测试。发布前使用 --include-ignored 运行它们，进行完整的本地验证。

必须提供的证据格式：报告实际的摘要行，而不是说“测试通过”。可接受的证据示例：

test result: ok. 87 passed; 0 failed; 5 ignored; 0 measured; 0 filtered out; finished in 3.42s

既存失败与新增失败的判定

如果门禁失败，请判断该失败是否在当前补丁之前就已存在：

# Stash current changes
git stash

# Run the failing gate at clean HEAD
cargo test -p <crate>

# If it also fails at HEAD: pre-existing failure — do not block the patch
# If it passes at HEAD: the patch introduced the regression — must fix

# Restore patch
git stash pop

报告：“该失败在 HEAD 中已存在，并非此次更改引入”或“该失败是新增的，由此补丁引入”。

单个 Crate 与整个工作区的范围

范围	命令	时机
单个 crate	cargo test -p <crate>	实现过程中的快速迭代
单个 crate（仅检查）	cargo check -p <crate>	最快——确认编译通过，不运行测试
单个 crate + 功能	cargo test -p trusty-common --features axum-server	需要功能标志时
工作区	cargo test --workspace	提交任何更改前必需
工作区 + 被忽略的测试	cargo test --workspace -- --include-ignored	标记发布版本前

修改共享库 Crate 之后

修改 trusty-common、trusty-mcp-core、trusty-embedder 或 trusty-symgraph 时：

1. 先运行 cargo check（整个工作区）——立即捕获所有依赖项中的编译错误。
2. 对已修改的库运行 cargo test -p <lib>。
3. 对导入已修改库的每个 crate 运行 cargo test -p <consumer>。
4. 只有所有依赖项的测试都通过后才能提交。

门禁摘要

cargo fmt --check          → Gate 1 (format)  — fix: cargo fmt
cargo clippy --workspace   → Gate 2 (lint)    — fix: address each warning
cargo test -p <crate>      → Gate 3 (tests)   — fix: repair failing tests

三项检查全部通过后，PR 才可合并。证据必须包含每项检查的原始输出。

反模式

• 在格式检查和 clippy 之前运行测试——如果格式检查失败，就会浪费时间。
• 只报告“测试通过”，却不展示结果摘要行。
• 将 ignored 计数视为失败——这些测试是有意跳过的。
• 因 HEAD 中已有的 open-mpm clippy 错误而阻塞工作。
• 用 cargo build 替代 cargo test——构建成功并不能验证行为。
• 在未确认 crate 名称别名的情况下，在整个工作区运行 cargo test（例如，使用 -p tga，而不是 -p trusty-git-analytics）。