casoon/judge

# judge ## 概述 `judge` 用于分析 Rust 工作区（workspace）的复杂度、代码重复、依赖规范性、架构边界、所有权、冗余信号（slop signals）以及基于 git 的高频修改区域（hotspots）。它被构建为一个 Cargo 子命令（二进制文件 `cargo-judge`），既可以作为 `cargo judge` 运行，也可以作为独立的 `cargo-judge` 运行。 其指导原则是：任何编译器或 Clippy 已经提示过的内容，`judge` 都不会重复。它涵盖了 crate 边界之上、跨 git 历史的维度，或者是聚合了多种工具的综合内容。 ## 状态 早期阶段。Fast Tier（无需构建，基于 `syn` 和 `gix`）以及 Deep Tier 的第一部分（基于 rust-analyzer，在 `deep` Cargo feature 之后）已经实现： - `cargo judge` — 汇总所有无需额外配置的检测器的发现结果，按严重程度由高到低排序 - `cargo judge inspect` — 通过 `cargo metadata` 检测到的 crate、源文件和入口点 - `cargo judge health [--score]` — 圈复杂度（cyclomatic complexity）、git 热点区域、语法级别的冗余信号，以及可选的健康评分（见下文） - `cargo judge dupes --mode strict|mild|weak|semantic` — 将重复的 token 跨度分组为克隆家族 - `cargo judge deps [--check-crates-io]` — 依赖类型的规范性检查以及本地命名冲突检查；crates.io 查询（`phantom-crate`、`phantom-version`、`fresh-low-reputation-dep`）是可选的（opt-in），因为 judge 默认不进行任何网络调用 - `cargo judge boundaries` — 基于可选的 `judge.toml` 配置的 crate 边界，以及依赖循环检测 - `cargo judge distribution` — 基于 git blame 的所有权和巴士因子（bus-factor）分析发现 - `cargo judge audit --since REF` — 限定于某个提交之后引入的发现结果的 pass/warn/fail 判定；需要预先保存的 baseline - `cargo judge dead-code [--include-tests]` — Deep Tier 功能，需要 `--features deep`（见下文） - `cargo judge explain --why-live` — Deep Tier 功能，需要 `--features deep`（见下文） - `--format json|sarif|markdown` — 所有报告命令均支持带版本控制的 JSON，生成报告的命令支持 SARIF 2.1.0，`audit`/`--baseline` 的差异比较支持 Markdown（适用于 PR 评论） - `--save-baseline` / `--baseline PATH` — 保存发现结果，或将其与 baseline 进行比较 尚未实现：模块级别的边界（目前仅有 crate 级别）、几项计划中的可维护性和依赖规范性规则，以及 MCP 服务器。 ## 健康评分 `cargo judge health --score` 会打印一个 0–100 的分数以及字母等级（A ≥90，B ≥80，C ≥70，D ≥60，F 为 60 以下）。扣分基于严重程度进行加权，并根据原创代码行数（authored-LOC）密度进行标准化；每个 crate 的加权配置可通过 `judge.toml` 开启。 客观局限性： - 该分数是一个可配置的趋势指标，而不是客观的质量排名。相对于 baseline 的变化量（delta）才是核心信息，而不是绝对的数值。 - 只有在使用 `--baseline PATH` 时才会显示趋势，并且只有当 baseline 是使用相同的评分公式版本和相同的 crate 配置生成时才会显示。否则，系统会明确报告为“不可比较”，而不会显示错误的偏差值。 - 当没有计算评分的依据时（例如没有原创代码行），该分数将被报告为不可用，并且 judge 会以退出码 2 退出 —— 绝不会给出虚假的满分。 ## 深度 Tier (`--features deep`) Deep Tier 会将工作区加载到 rust-analyzer（`ra_ap_ide`、`ra_ap_load-cargo`）中，以处理真实的引用数据，而不是基于语法的猜测。构建它会编译 `ra_ap_*` crate，这比默认构建耗时明显更长。 - `cargo judge dead-code [--include-tests]` — 报告 `unused-pub-workspace`：即那些没有被其他工作区 crate 引用，**且**没有从自身 crate 的已识别入口点可达的 `pub` 项。这意味着“在当前检查视图中未发现使用”，并不代表已被证明是死代码。`--include-tests` 会将仅在 `#[test]` 中的引用算作使用（默认关闭）。发现结果会带有证据（根集大小、已搜索的 crate、置信度原因），以便您自行判断其可信度。 - `cargo judge explain --why-live` — 从已识别的入口点（二进制文件/示例中的 `fn main`；带 `--include-tests` 时的测试和基准测试；以及始终作为入口的 `#[no_mangle]`/`#[export_name]`/`#[wasm_bindgen]`）到目标项的最短且带证据的调用路径。每条边都被分类为 `static`/`dynamic`/`macro`/`generated`/`unknown`。 已知限制：加载工作区时没有使用 proc-macro 服务器，也没有运行构建脚本，因此由 proc macro 或 `build.rs` 生成的代码对分析是不可见的。通用注册宏也无法被识别 —— 一个只能通过此类宏触达的项可能会被报告为未使用。 ## 为什么选择 judge - 确定性的发现结果，不仅对人类易读，对编程代理（coding agents）同样友好 - 不是 linter，不是 formatter，也不是安全扫描器 —— 它是对 Clippy/cargo-audit 的补充，而不是替代 - 无 SaaS，无遥测，无需账号 ## 安装 需要 Rust 1.95+（2024 edition）。 ### 从源码构建 ``` git clone https://github.com/casoon/judge.git cd judge cargo build --release ./target/release/cargo-judge --help ``` ### cargo install (本地路径) ``` cargo install --path . --force ``` ## 用法 ``` cargo judge # combined findings, worst first cargo judge inspect # crates, entry points, detected tiers cargo judge dupes --mode mild # duplicated token spans (clone families) cargo judge deps --format json # dependency findings as JSON cargo judge health --score # health score, 0-100 + letter grade cargo judge --save-baseline # save .judge/baseline.json cargo judge --baseline .judge/baseline.json cargo judge audit --since origin/main # pass/warn/fail verdict for a PR cargo judge dead-code # Deep Tier — binary must be built with --features deep ``` ## 来源归属 (Provenance Attribution) `cargo judge provenance` 将代码变动（churn）、重复和抑制债务（suppression debt）进行细分 根据启发式分类的作者类别（如提交尾注/标记 如 `Co-authored-by: Claude`，或配置的 `[[provenance_label]]`）。它是 可选的（opt-in） — 不是纯粹的 `cargo judge` 的一部分 — 并且总是会打印以下警告： ## 开发 ``` cargo build cargo test cargo test --features deep # includes the Deep Tier (slow first build) ``` 可选的 Cargo feature： | Feature | 增加的功能 | 构建命令 | |---|---|---| | `deep` | 基于 rust-analyzer 的深度分析层（`ra_ap_ide`、`ra_ap_load-cargo`） | `cargo build --features deep` | ## 许可证 MIT，详见 [LICENSE](LICENSE)。

标签：Rust, 云安全监控, 代码复杂度, 依赖管理, 可视化界面, 死代码检测, 网络流量审计, 通知系统, 静态分析