bot-metric:面向 Rust 项目、Workspace 与单个源码文件的代码度量和质量分析工具，用于统一统计代码规模、复杂度、重复率、unsafe 使用与规则问题，并生成口径明确、可复核、可比较的结构化工程报告，帮助团队持续掌握代码质量变化，构建稳定、可判定、可追溯的 Rust 质量度量流程。

---

🤔 这是什么

BotMetric 是 Rust 源码体检工具。它读取 Cargo package、workspace 或单个 .rs 文件，输出规模、函数、复杂度、重复、unsafe 密度以及可定位的质量发现条目，并为每项结果记录统计范围和可信度。

默认分析只读，不修改源码、不运行项目二进制或测试。只有显式启用 --cargo-check、--rustc-check 或 --clippy-check 时，才会调用外部编译器收集诊断；编译失败不会抹掉已经完成的源码指标，而是将报告标为 partial。

你想知道什么	BotMetric 给出的结果
项目有多大	NBNC 代码行、文件规模和函数体规模。
哪些位置值得优先检查	超大文件/函数、复杂度、unsafe 和重复发现条目。
结果能否比较	每项指标带分子、分母、范围、状态、算法和可信度；比较基准可计算增量。
编译器发现了什么	可选保留 rustc/Cargo/Clippy 的原始诊断、位置与错误码。

当前源码分析以词法事实和 syn 3.x AST 为主，不假装提供类型解析、trait 求解、过程宏展开后 AST 或完整跨 crate 调用图；这些能力应由 rustc 或其他工具补充。

---

🛠️ 安装

需要 Rust 1.89+ 和 Cargo，支持 macOS、Linux 与 Windows MSVC。编译诊断仅用于可信项目。

cargo install bot-metric --version 1.2.3 --locked
bot-metric --version

---

🚀 快速开始

Cargo 项目：

cd /path/to/rust-project
bot-metric analyze

指定 workspace 或 package：

bot-metric analyze --manifest-path /path/to/Cargo.toml
bot-metric analyze --manifest-path /path/to/Cargo.toml --package app

单个文件：

bot-metric analyze /path/to/file.rs --edition 2021

需要结构化结果：

bot-metric analyze --format json --output bot-metric-report.json
bot-metric analyze --format sarif --output bot-metric.sarif

需要编译器诊断时显式打开：

bot-metric analyze --cargo-check
bot-metric analyze /path/to/file.rs --edition 2021 --rustc-check

---

🗺️ 能力地图

flowchart LR
    A[Cargo 项目] --> C[统一源码快照]
    B[单个 .rs 文件] --> C
    C --> D[词法事实]
    C --> E[syn AST]
    C --> F[Cargo target / cfg]
    D --> G[规模 / 重复 / unsafe]
    E --> H[函数 / 复杂度 / 规则]
    F --> I[范围与聚合]
    G --> J[Text / JSON / SARIF]
    H --> J
    I --> J
    K[可选 cargo/rustc/clippy] --> J

能力	说明
输入发现	读取 package、workspace、target、edition、feature 和本地模块；单文件不要求 manifest。
规模与复杂度	NBNC、文件/函数行数、圈复杂度和超阈值比例。
安全与重复	覆盖 unsafe block/fn/trait/impl，检测完整重复文件和连续代码窗口。
规则发现条目	以 BM 编号、文件位置、原因、定义和建议输出可修复问题。
cfg 与聚合	对 target/cfg 做三态判断，按选择的 scope 与 aggregation 汇总。
编译诊断	可选读取 Cargo、rustc 或 Clippy，保留原始渲染和错误码。
基线	在相同配置和范围下比较指标增量、新增与已解决发现条目。

---

🧭 命令与配置

日常入口按分析目标组织：

任务	命令	分析范围
查看整个 Cargo 项目	bot-metric analyze	当前项目源码树，共享文件只统计一次。
查看一个 Rust 文件	bot-metric analyze path/to/file.rs	只读取指定文件，不要求 manifest。
连同本地模块一起查看	bot-metric analyze path/to/file.rs --resolve-modules	从指定文件继续发现本地 mod。
检查某个 target	bot-metric analyze --target app --scope reachable	只读取该 target 能够到达的本地代码。
按团队策略门禁	bot-metric check PATH --config bot-metric.toml	按配置生成发现条目并决定退出码。
保存或比较基准	baseline create / baseline compare	在相同配置和范围下比较质量变化。

默认使用 scope = auto 和 aggregation = physical：Cargo 项目扫描源码树，每个物理文件只统计一次。只有需要比较不同 target/cfg 实际看到的代码时，才使用 --scope reachable --aggregation view。

常用选项包括 --package、--target、--features、--include-tests、--resolve-modules、--format、--config、--cargo-check 和 --clippy-check。完整参数以 bot-metric <command> --help 和命令手册为准。

团队配置可以从下面这份门禁示例开始。quality_targets 默认启用；这里显式写出目标，方便评审和比较基准复用。

[analysis]
source_scope = "auto"
aggregation = "physical"

[thresholds]
huge_file_lines = 2000
huge_function_lines = 50
huge_complexity = 20
duplication_min_lines = 10
duplication_max_findings = 20
duplication_snippet_lines = 18
duplication_max_index_bytes = 536870912
duplication_max_verifications = 10000000
duplication_output_bytes = 0 # 0 表示不限制报告大小
finding_arena_bytes = 16777216
finding_spill_bytes = 536870912

[rules]
duplication_findings = "off" # off | top | all
unknown_policy = "fail"
blocking_severities = ["warning", "error"]
blocking_rules = []

[quality_targets]
item_target = "none" # item selector 下可设为 "input" 或 "each_item"
max_average_file_lines = 300
max_average_function_lines = 30
max_average_cyclomatic = 5
max_code_duplication_ratio = 0.10
max_file_duplication_ratio = 0.04
max_unsafe_density = 0.10
max_code_size_growth_ratio = 0.0
disabled_targets = []

duplication_findings = "off" 仍会计算重复率，只是不生成 BM006/BM007 位置发现条目；需要审查具体重复片段时改为 top 或 all。blocking_severities 使用程序默认的 warning/error；如果团队只希望 error 阻塞，可显式改成 ["error"]。

max_code_size_growth_ratio 只有在 check --baseline FILE 时才有比较基准的意义。命令行阈值优先于配置文件，配置、质量目标和缓存语义见配置手册。

重复检测字段怎样影响大项目

字段	作用
duplication_max_findings	top 模式最多输出的发现条目组数，不截断入选组的位置。
duplication_snippet_lines	终端重复片段的上下文行数，位置列表不截断。
duplication_max_index_bytes	重复窗口索引内存上限；超限时指标变为 partial 并记录 BM202。
duplication_max_verifications	候选和文件字节精确复核上限；超限时保留已验证下界并记录 BM202。
duplication_output_bytes	报告大小上限；0 表示不限制，超限不会写出截断报告。
finding_arena_bytes	发现条目预物化的内存预算；超出后转入临时存储。
finding_spill_bytes	发现条目临时存储总预算；超限会明确标记不完整，不静默丢弃。

---

📦 输出与结果

人类可读输出

人类可读模式固定先回答“分析是否完成”，再回答“应该检查哪里”：

Execution Status
  status:                Complete
  origin:                Cargo
  aggregation:           Physical
  files:                 42
  metrics:               43
  findings:              2
  compiler diagnostics:  0
  analysis errors:       0

  Scope
    source scope:    Tree
    packages:        1
    targets:         2
    views:           2
    compiler check:  not requested

  Codebase
    code lines:  12,480
    functions:   436

  Key Metrics
    avg file lines:      297.1 lines
    avg function lines:  21.4 lines
    avg complexity:      2.7
    code duplication:    4.82%
    unsafe density:      0.03%

  Finding Breakdown
    BM001      1  functions too large
    BM004      1  functions too complex

Diagnostics
warning[BM001]: function `parse` is too large
  --> src/parser.rs:18:8
   |
 18 | pub fn parse(...) {
   |        ^^^^^
  = reason: 73 code lines exceed the limit of 50 by 23
  = definition: code lines exclude blanks and comment-only lines
  = help: extract cohesive steps into helper functions

终端会列出每条发现条目的文件位置、源码范围、reason、definition 和 help；编译器问题优先保留 rustc 原始渲染。没有可靠源码位置时只展示消息和日志证据，不伪造行号。

规则与运行诊断

诊断码	机器规则 ID	含义
BM001	rust.function.too_large	函数体代码行数超过配置上限。
BM002	rust.safety.unsafe_usage	unsafe 函数或代码块需要审查。
BM003	rust.file.too_large	文件代码行数超过配置上限。
BM004	rust.function.too_complex	函数圈复杂度超过配置上限。
BM006	rust.code.duplicated_block	规范化 NBNC 代码片段超过重复阈值。
BM007	rust.file.exact_duplicate	文件原始字节完全相同。

运行链路中的 partial/error 也使用稳定编号：BM100–BM199 表示输入与目录扫描，BM200–BM299 表示语法和源码事实，BM300–BM399 表示 Cargo/rustc 启动、超时或非零退出，BM400–BM499 表示配置、输出、比较基准和契约错误。rustc 的 E#### 等原始错误码保持不变，不映射为 BM。

机器输出与契约

输出	适用场景
JSON	读取状态、能力矩阵、指标、diagnostics 和发现条目。
SARIF	上传到代码扫描或 CI 平台。
Baseline	在相同配置与范围下比较质量变化。

报告中的每项指标包含 numerator、denominator、scope、status、algorithm_id 和 confidence；其中 confidence 表示可信度。NBNC、函数体范围、重复窗口、unsafe 覆盖和 not_applicable/unknown/partial 的判定口径见指标与发现条目。

退出码为：0 完整且通过，1 阻塞性发现条目，2 CLI/配置/输入错误，3 报告已写出但分析或编译诊断不完整，4 保留兼容。自动化应同时读取退出码和报告状态。

BotMetric 1.2.3 的新报告使用 analysis-report-1.2.3.json 的版本化 Schema URI，并以 compiler_run.timed_out 明确区分编译器超时与普通非零退出；已发布的 1.2.1 和 1.2.0 报告 Schema 保持不变，供消费者按 URI 选择。component-info.json 会声明当前报告契约；BotGate 接入时应声明产物路径并直接读取 diagnostics[]，不要解析人类可读文本。

---

📚 文档

入口	适合解决的问题
使用手册	从输入选择到配置、报告、CI 和发布。
输入与分析	Cargo、单文件、scope、cfg 和模块发现。
指标与发现条目	公式、阈值、规则码和状态口径。
报告与契约	JSON/SARIF、Schema、比较基准和组件接口。
BotGate 集成	在质量门禁中消费分析产物。
基准说明	复现性能数据与资源预算。
发布与兼容性	构建、打包、平台验证和契约检查。

---

版本边界

本发布说明对应 BotMetric 1.2.3，Rust edition 为 2024，MSRV 为 Rust 1.89。analysis-report-1.2.0.json 和 analysis-report-1.2.1.json 是已发布兼容契约，analysis-report-1.2.3.json 是当前结构化编译器超时报告契约；这些 URI、component-info.json 能力契约、CLI 行为、配置字段、BM 诊断编号、退出码和组件集成约定属于兼容边界。内部 Rust 模块、实现细节和未声明的扩展字段不属于稳定 API 承诺。