BrokkAi/usagebench

# usagebench 这是一个精选基准测试代码库，主要围绕以下静态分析任务： 发现源码符号的使用情况。 [`docs/`](docs/README.md) 下的 Starlight 站点解释了对比 方法论、当前的 Bifrost 与 LSP 结果对比，以及各案例级别的语言 差异。 基准测试语料库是按源码位置编写的，而不是按特定分析器的符号 ID 编写。 每个案例都指向一个声明、预期的使用位置，以及使用 LSP 格式 range 的从使用反查到声明的探测。 ## 目录结构 * `benchmarks`：编写的基准测试案例文件和语料库文档。 * `fixtures`：基准案例使用的小型库内源码语料库。 * `schema`：基准测试案例文档的 JSON Schema。 * `src`：Rust 验证 CLI、schema 模型和分析器运行器适配器。 * `adapters/lsp`：版本化的 language-server 配置和复现说明。 * `containers/reference`：版本化且通过 digest 锁定的参考环境。 * `scripts`：本地镜像构建、离线执行和报告复现工具。 * `docs`：公开的 Starlight 内容，以及适配器设计说明和执行计划。 ## 验证基准测试案例 基准测试案例使用基于 LSP 格式位置模型编写的 YAML。使用以下命令验证它们： ``` cargo run -- validate benchmarks/cases ``` CI 运行相同的 Rust 测试和验证流程： ``` cargo test cargo run -- validate benchmarks/cases ``` ## 开发语料库 当前的语料库使用 Java、Go、Python、TypeScript、 JavaScript、Rust、Scala、C#、PHP、C++ 和 Ruby 的小型签入 fixtures。这些 fixtures 是 issue #8 的真实数据源；旧的宽泛 Java/Go/Python 生成器栈已从当前的基准测试路径中移除。 每个文档均为 schema v2，并明确标记为 `development`、 `analyzer_informed` 和 `legacy_unattributed`。它是一个用于回归和诊断的语料库，尚不是经过独立审查的评估分区。每个 fixture 案例都记录了 `verification.method: manual_inspection`，并附有简短说明，解释了其位置是如何检查的。 ## 分析器运行器 `src/runners` 下的运行器适配器将特定工具的输出转换为一种分析器中立的报告格式。每份报告都会记录请求和已解析的工具版本，以及按操作划分的能力级别（`native`、`recovered` 或 `unsupported`）。报告区分了精确通过、位置未验证的结果、严重失败和运行器错误，并将开发总计与评估总计分开。使用以下命令打印 JSON Schema： ``` cargo run -- report-schema ``` 现有的 Bifrost 命令保持稳定： ``` cargo run -- run-bifrost benchmarks/cases \ --bifrost-repo /path/to/bifrost \ --bifrost-working-tree ``` 通用 LSP 适配器会启动一个版本化的 stdio language server，打开一个隔离的 fixture 工作区，并将协议原生的 references、 definition 和 type-definition 响应转换为相同的报告： ``` cargo run -- run-lsp benchmarks/cases \ --profile adapters/lsp/gopls.json \ --output benchmark-output/gopls-v0.23.0.json ``` 配置通过 clangd、Roslyn 和 csharp-ls、gopls、Eclipse JDT LS、Pyright、Ruby LSP、Metals、Intelephense、 rust-analyzer 和 typescript-language-server 覆盖了所有十一种语料库语言。配置中指定的可执行文件必须已安装，或者可通过配置的包启动器访问；`--server-command` 只能覆盖该可执行文件，同时保留其参数。有关设置和 测量的对比，请参阅 [LSP 配置指南](adapters/lsp/README.md)。 UsageBench 有意将重点放在查找符号引用以及将这些引用导航回声明和类型的 LSP 格式任务上。 更广泛的分析合约应使用同级套件——例如，用于 call-graph 解析的未来 `callbench` 和用于 taint-flow 分析的 `taintbench`—— 这样每个基准测试都可以在不受特定工具的私有 hooks 或弱化语义影响的情况下，建立自己的真实参考标准。 ## 发布、引用和许可 基准测试语料库发布使用不可变的 SemVer 标签，例如 `v0.1.0`。基准测试发布版本独立于 `Cargo.toml` 中的 Rust 包版本和基准测试文档的 `schemaVersion`。有关版本策略和精选发布内容，请参阅 [`RELEASES.md`](RELEASES.md)。 引用 UsageBench 时，请使用根目录下的 [`CITATION.cff`](CITATION.cff)。它描述了 最新版本，并且有意不包含占位符 DOI。如果档案服务稍后分配了 DOI，真实的特定版本标识符将被添加到引用文件和该版本的说明中。 运行报告记录： - `usagebenchVersion`：Rust CLI 和适配器实现版本； - `usagebenchRevision`：确切的 UsageBench commit，当本地更改导致无法仅通过 commit 复现时，带有 `-dirty` 标记； - `usagebenchRelease`：可用的 `vMAJOR.MINOR.PATCH` 语料库标签；以及 - 逻辑调用、原生或容器平台范围、分析器可执行文件校验和、工具链、参考环境定义，以及运行器请求和已解析的版本。 参考环境版本 1 为 Bifrost 和 gopls 提供了规范的 `linux/amd64` 路径。将发布的容器报告保存为 `report.json`，解压报告指定的发布包，然后运行一条命令： ``` ./scripts/reproduce-report.sh report.json reproduced.json ``` 该命令会在本地构建记录的环境，在没有网络的情况下重新运行，并从语义上比较报告。该项目有意不向 GHCR 发布镜像，也不承诺提供预构建镜像；发布包包含了构建它们所需的一切。有关 artifact 审查流程、安全边界、预期构建成本和手动命令，请参阅 [`ARTIFACT.md`](ARTIFACT.md)。原生运行器命令仍可用于开发，但被标记为特定于宿主机，且不是规范的可复现性声明。 如果 `usagebenchRevision` 以 `-dirty` 结尾或缺少 `usagebenchRelease`，则该报告标识为开发运行，并会被规范复现命令拒绝。 UsageBench 采用宽松的 [MIT License](LICENSE.md) 授权，涵盖了 本代码库中的语料库 fixtures、断言、适配器配置和测试工具代码。 ## 每日 Bifrost 基准测试 `.github/workflows/benchmark.yml` 中的每日 GitHub Actions 工作流会在 `ubuntu-latest` 上针对 Bifrost 运行精选的语料库。 该工作流： * 验证 `benchmarks/cases` * 签出 `BrokkAi/bifrost` * 构建 `usagebench` * 运行 `usagebench run-bifrost benchmarks/cases` * 上传来自 `benchmark-output` 的 JSON 报告 * 发布 GitHub 步骤摘要 * 可选地向 Slack 发送 payload 计划运行使用 Bifrost `master`。手动 `workflow_dispatch` 运行可以设置特定的 `bifrost_ref`，并可以选择加入标记为 `unsupported` 的案例。 如果没有 `--bifrost-working-tree`，`run-bifrost` 会在 `target/usagebench` 下创建一个隔离的签出，并签出 `--bifrost-commit`。 如果默认的 `GITHUB_TOKEN` 无法读取 `BrokkAi/bifrost`，请配置一个名为 `BIFROST_CHECKOUT_TOKEN` 的仓库 secret，并授予对该 repo 的读取权限。 Slack 投递为尽力而为，且不会更改基准测试结果。要启用此功能，请配置仓库 secret `SLACK_DAILY_USAGEBENCH_WEBHOOK_URL`。该工作流会发送一个特定于基准测试的 payload，包含： * `ok` * `error_text` * `workflow_run_url` * `head_sha_short` * `usagebench_revision` * `usagebench_release` * `bifrost_ref` * `bifrost_sha_short` * `run_outcome` * `cases_count` * `passed_count` * `improved_count` * `total_passed_count` * `failed_count` * `expected_failures_count` * `not_planned_count` * `unsupported_count` * `skipped_count` * `errors_count`

标签：LSP, Rust, 云安全监控, 代码分析, 凭证管理, 可视化界面, 网络流量审计, 请求拦截, 通知系统, 静态分析