SpecHygiene

找出你的 Reqnroll / SpecFlow BDD 套件中的冗余。
未使用的代码、未使用的 step 定义以及 feature 文件数据错误 — 纯静态分析，无需 AI，无需联网。

将其指向你的解决方案文件夹，它会报告哪些部分正在腐化：无人调用的 C# 代码、没有场景使用的 step 定义，以及包含损坏数据的 feature 文件。 **纯静态分析 — 无需联网、无需 AI、无需运行测试。** ## 实际效果 ▶ **[查看实时示例报告](https://karzone.github.io/SpecHygiene/sample-report.html)** — 基于目录 [`samples/demo`](samples/demo) 中的小型演示生成，它展示了每项检查中的发现结果。 ## 检查内容 | 检查项 | 发现的问题 | |-------|---------------| | **未使用的代码** | 失效的 C# 代码 — 没有任何引用的方法、类和接口，使用 Roslyn 的语义模型（基于符号的精确匹配，而非文本匹配）。 | | **未使用的 step 定义** | **没有任何场景使用**的 `[Given]`/`[When]`/`[Then]` 绑定，使用与 Reqnroll 运行时相同的 Cucumber 表达式 / 正则表达式语义进行匹配 — 因此不会出现误报“未使用”。 | | **数据错误** | Feature 文件问题：未定义的 ``、带有 `Examples:` 表格的 `Scenario`（应为 `Scenario Outline`）、格式错误的数据表格、无法解析的 `@DataSource` CSV。 | ## 安装 最简单的方法 — 作为 .NET 全局工具： ``` dotnet tool install -g SpecHygiene spechygiene /path/to/your/solution ``` 稍后可以使用 `dotnet tool update -g SpecHygiene` 进行更新。 需要安装 [.NET SDK](https://dotnet.microsoft.com/download)（8 或更高版本）。该工具在 **.NET 8、9 和 10** 上运行 — 并且它分析的是源代码，因此适用于针对上述任何版本的代码库，包括 .NET 10 / C# 14。

或者从源码运行

``` git clone https://github.com/Karzone/SpecHygiene.git cd SpecHygiene dotnet build -c Release dotnet run --project src/SpecHygiene -- /path/to/your/solution ```

首先在自带的演示中尝试一下： ``` spechygiene ./samples/demo # if installed as a tool # 或 dotnet run --project src/SpecHygiene -- ./samples/demo ``` ## 使用方法 ``` spechygiene [checks] [--out ] Checks (default: all): --unused-code Roslyn dead-code (unused methods/classes/interfaces) --unused-steps Step definitions no scenario uses --data-errors Feature-file data errors (undefined placeholders, etc.) --all Run every check (default when none specified) Options: --out Output directory (default ./reports) -h, --help Show this help ``` 示例： ``` # 仅 unused-step-definition 检查 dotnet run --project src/SpecHygiene -- /path/to/solution --unused-steps # 两项检查，自定义输出文件夹 dotnet run --project src/SpecHygiene -- /path/to/solution --unused-code --data-errors --out ./hygiene ``` ## 报告 每次运行都会写入输出目录（默认为 `./reports`）： | 文件 | 内容说明 | |------|-----------| | **`spechygiene-report.html`** | 一个独立的 HTML 报告 — 包含每项检查的汇总卡片，以及一个列有所有发现结果及其文件/行号位置的表格。支持浅色和深色模式。 | | **`summary.txt`** | 纯文本格式的计数摘要 — 非常适合用于 CI 日志。 | 控制台在运行时会打印相同的摘要。 **HTML 是如何生成的** — 每次运行都会自动生成（除非你在 `appsettings.json` 中将 `Output.GenerateHtml` 设置为 `false`）。它是一个**包含所有内联 CSS 且没有 JavaScript 或外部资源的单一文件**，因此完全可以在离线状态下工作，并且可以安全地通过电子邮件发送或存档。 **如何查看** — 只需在任何浏览器中打开该文件即可： ``` # macOS open reports/spechygiene-report.html # Windows start reports\spechygiene-report.html # Linux xdg-open reports/spechygiene-report.html ``` 或者直接查看从该仓库渲染的**[实时示例报告](https://karzone.github.io/SpecHygiene/sample-report.html)**。 ## 配置 默认设置位于 [`src/SpecHygiene/appsettings.json`](src/SpecHygiene/appsettings.json) 中，并且可以进行调优 — 包括扫描路径、feature 文件匹配模式、step 定义的 glob 匹配、排除列表、阈值，以及启用哪些检查。对于扫描路径和运行的检查项，命令行参数具有最高优先级。 ``` { "Analysis": { "FeatureFilePattern": "*.feature" }, "CoverageAnalysis": { "Enabled": true, "UseSyntacticDiscovery": true }, "UnusedCodeAnalysis": { "Enabled": true, "IncludePublicMembers": false } } ``` ## 工作原理 - **未使用的 step 定义** — 使用 Roslyn 解析你的 `*Steps.cs` 以发现绑定（遵循 `[Binding]` 继承和单纯的方法名约定绑定），然后使用 Reqnroll 在运行时使用的相同表达式语义（Cucumber 表达式、正则表达式、可选文本 `(s)`、交替 `a/b` 和参数类型）将每个 feature 文件中的 step 与它们进行匹配。绑定了的 step 即为“已使用”；没有 step 触达的绑定则被报告为未使用。 - **未使用的代码** — 构建 Roslyn 编译并遍历符号引用，因此对于那些仅仅看起来是通过名称调用的重载，也能做出正确的判断。测试方法、hooks、控制器和序列化入口点会通过 attribute 进行排除，因此不会被误报。 - **数据错误** 来源于一次轻量级的 feature 文件解析过程。 ## 开发 ``` dotnet build # build the solution dotnet test # run the test suite (217 tests) ``` ``` src/SpecHygiene # the CLI + analysis engine tests/SpecHygiene.Tests # xUnit tests, incl. a matcher eval corpus samples/demo # a tiny solution that triggers every check ``` 匹配器测试包含一个 **eval corpus** — 这些绑定/step 用例的预期结果均基于真实的 Reqnroll 运行时行为进行锚定，因此对匹配逻辑的修改将以事实为依据进行把关，而非仅凭直觉。 ## 贡献 欢迎提交 Issues 和 pull requests。请在提交 PR 之前运行 `dotnet test`。 ## 许可证 [MIT](LICENSE) © Karthik Kalaiyarasu

标签：BDD, Reqnroll, SpecFlow, 云安全监控, 多人体追踪, 死代码检测, 静态分析