sigee-min/vibeguard-cpp

# VibeGuard C++ 一个轻量级的C++代码质量治理工具，用于扫描、建立基准线并管理任何代码库中的架构债务。 VibeGuard C++ 是一个面向C++代码库的命令行质量治理工具。它将文件、命名空间、类、函数、参数、全局变量、调用、全局状态访问以及所有权关系索引到一个本地本体中，然后利用该结构来跟踪架构违规和遗留代码债务。 其命令行二进制文件是 `vgcpp`。当命令需要项目规则时，它会读取 `.vgcpp.yml` 文件，将扫描输出写入 `.vgcpp/` 目录下，并支持基于基准线的CI检查。 ## 核心工作流程 ``` vgcpp init vgcpp scan --config .vgcpp.yml --compile-db build/compile_commands.json --storage sharded-json vgcpp arch check --config .vgcpp.yml vgcpp dep graph --root . --compile-db build/compile_commands.json --output .vgcpp/dependency-graph.json vgcpp dep discover --root . --license-map .vgcpp/licenses.yml --output .vgcpp/discovered-dependencies.yml vgcpp dep discover --root . --mode resolved --output .vgcpp/discovered-dependencies.yml vgcpp dep check --config .vgcpp.yml vgcpp debt list --kind all --config .vgcpp.yml vgcpp suppress suggest --finding --report .vgcpp/report.json --config .vgcpp.yml vgcpp global report --config .vgcpp.yml vgcpp baseline create --config .vgcpp.yml vgcpp baseline diff --baseline .vgcpp/baseline.json vgcpp baseline accept --baseline .vgcpp/baseline.json --config .vgcpp.yml vgcpp baseline prune --baseline .vgcpp/baseline.json --config .vgcpp.yml vgcpp baseline stats --baseline .vgcpp/baseline.json vgcpp gate --baseline .vgcpp/baseline.json --config .vgcpp.yml vgcpp hotspot list --report .vgcpp/report.json --config .vgcpp.yml --churn .vgcpp/churn.csv vgcpp trend record --baseline .vgcpp/baseline.json --output .vgcpp/trends/current.json vgcpp trend report --previous .vgcpp/trends/previous.json --current .vgcpp/trends/current.json vgcpp export sarif --output .vgcpp/vgcpp.sarif --config .vgcpp.yml vgcpp export html --output .vgcpp/html --config .vgcpp.yml --trend .vgcpp/trends/current.json --hotspots .vgcpp/hotspots.json --dependency-graph .vgcpp/dependency-graph.json vgcpp report ``` `vgcpp init` 会创建一个包含架构、全局状态、复杂度、债务和存储默认配置的初始 `.vgcpp.yml` 文件。 ## 策略与过滤 `vgcpp` 通过三个层级应用 `.vgcpp.yml` 策略： - **抑制措施**：从所有输出中移除已被接受的发现。 - **规则策略**：启用或禁用规则，分配严重性，并控制门控行为。 - **输出过滤器**：隐藏展示冗余信息，同时不删除基准线证据。 使用 `policy.rules` 进行规则级别的严重性设定和门控决策，使用 `output` 过滤器控制控制台、SARIF和HTML的输出展示。SARIF和HTML导出使用相同的导出模型和经过策略过滤的发现集合，因此规则元数据、来源和稳定的发现指纹在两种格式中保持一致。 使用 `vgcpp suppress suggest --finding ` 可以为被接受的债务或外部调用的API生成可审查的YAML代码片段。对于实时的外部入口点，建议使用 `api_boundary`；对于有意接受的本地债务，建议使用 `suppressions`。 关于本仓库的GitHub代码扫描自扫描配置，请参阅 `.github/workflows/vgcpp-code-scanning.yml` 和 `docs/integrations/github-actions.md`。 要运行仓库自用的误报测试套件，请执行 `./tools/dogfood/run-self-scan.sh`；阈值策略记录在[docs/dogfood.md](docs/dogfood.md)中。 产品化工作流程文档： - 策略治理：[docs/policy-governance.md](docs/policy-governance.md) - GitHub Actions集成：[docs/integrations/github-actions.md](docs/integrations/github-actions.md) - 打包：[docs/packaging.md](docs/packaging.md) - 自用测试：[docs/dogfood.md](docs/dogfood.md) 依赖元数据和依赖拒绝规则在 `.vgcpp.yml` 中配置： ``` dependencies: - name: boost version: 1.84.0 license: BSL-1.0 include_paths: - third_party/boost/ dependency_rules: - from: domain deny: - boost global_state: max_readers: 5 max_writers: 1 complexity: max_cyclomatic_complexity: 10 max_parameters: 6 max_cognitive_complexity: 15 max_nesting_depth: 4 storage: format: sharded-json dependency_discovery: resolved_graph: .vgcpp/dependency-graph.json use_resolved_include_paths: false ``` `vgcpp dep discover --license-map ` 命令可以通过一个小型YAML映射文件，为发现的CMake、vcpkg和Conan依赖项丰富元数据： ``` licenses: fmt: MIT openssl: Apache-2.0 ``` 未包含在映射文件中的依赖项，其 `license:` 字段将保持为空，以便 `DEP-002` 继续标记那些仍需审查的元数据。 `vgcpp dep graph` 命令从CMake文件API回复、编译命令包含根目录、vcpkg清单和锁文件、Conan清单和锁文件中，生成一个确定性的本地包图。团队可以审查该产物，然后要么使用 `vgcpp dep discover --mode resolved` 将其转换为 `.vgcpp.yml` 的存根，要么选择在扫描期间通过设置 `dependency_discovery.use_resolved_include_paths: true` 来使用其包含路径的所有权信息。手动编写的 `.vgcpp.yml` 依赖条目仍具有规范性，并在冲突时优先。 ## 当前能力集 - 基于 `compile_commands.json` 的 Clang LibTooling 扫描 - 为扫描自动配置打包好的 Clang 驱动程序和资源目录默认值 - 符号和关系边 JSON 报告输出至 `.vgcpp/report.json` - 函数调用和全局读写关系边收集 - 从配置的依赖包含路径进行依赖图索引 - 从简单的 CMake、vcpkg 和 Conan 声明中发现可审查的依赖清单，并支持可选的许可证映射丰富 - 基于本地 CMake 文件 API、编译数据库、vcpkg 和 Conan 元数据生成确定性的已解析依赖图 - 对项目本地的类、结构体和枚举类型使用局部变量类型 - 具有可配置宏展开过滤功能的宏来源元数据 - 可选启用函数级局部别名/数据流精度以优化全局读写关系边 - 每函数复杂度和风险评分 - 对分层、拒绝规则、架构策略、抑制措施、依赖元数据、依赖规则、策略过滤、作用域、API边界、精度和输出设置的严格 `.vgcpp.yml` 解析 - 分段的架构规则检查，规则编号从 `ARCH-001` 到 `ARCH-007` - 依赖元数据和依赖使用情况检查，规则编号从 `DEP-001` 到 `DEP-003` - 未使用参数、未使用内部函数、未使用全局变量、未使用局部变量和未使用私有成员的债务检查，规则编号从 `DEBT-001` 到 `DEBT-005` - 全局状态扇入检查，规则编号从 `GLOBAL-001` 到 `GLOBAL-003` - 复杂度阈值发现，规则编号从 `COMP-001` 到 `COMP-004` - 针对大型项目的可选分片JSON扫描存储，位于 `.vgcpp/index/` 目录下 - 从同一个经过策略过滤的导出模型生成SARIF和静态HTML导出，并具有匹配的稳定指纹和来源元数据 - 基准线创建、差异比较、接受、剪枝和统计，具有稳定的发现ID - 用于新增架构、依赖、债务、全局状态和复杂度发现的CI门控策略 - 结合发现数量、复杂度/债务/全局类别、函数风险和可选代码变更频率的热点排名 - 用于跟踪架构和债务是否随时间改善的趋势快照和报告 - 基于最新扫描的结构化控制台报告 - 为被接受的债务和外部API入口点提供可审查的抑制建议 ## 运行时预期 用户需提供一个可构建的C++项目和一个 `compile_commands.json` 文件。 打包好的构件包含了用于扫描的Clang运行时默认配置。 Windows的默认源代码构建已在CI中进行了不依赖LibTooling的检查。Windows的Clang扫描和Windows包的运行时支持尚未正式发布，直到CI拥有完整的LLVM/Clang开发包表面并通过包冒烟测试路径。在支持的发布平台上，打包用户应该不需要LLVM/Clang开发包。 `vgcpp dep graph` 命令是本地且可审查的：它读取磁盘上已存在的项目元数据，不会安装包、查询远程注册表或解决包版本问题。 包通过CPack构建；有关本地包命令和已安装文件，请参阅[docs/packaging.md](docs/packaging.md)。 ## 产品定位 VibeGuard C++ 适用于需要在持续交付的同时保持大型C++代码库结构健康的团队。它不是一个代码格式化器，不是一个内存漏洞扫描器，不是 `clang-tidy` 的替代品，也不是一个通用的缺陷查找器。 基准线、门控、热点和趋势命令构成了质量管理循环：接受已知债务、在CI中阻止回归、将修复工作集中在最高风险的文件上，并报告总体和分类级别的发现数量是否在向正确的方向发展。 ## 许可证 VibeGuard C++ 采用MIT许可证发布。详见[LICENSE](LICENSE)。

标签：AI红队测试, Bash脚本, C++ 编程, Homebrew安装, 代码扫描工具, 代码质量检测, 依赖管理, 债务跟踪, 基线管理, 多模态安全, 开源框架, 技术债务管理, 持续集成, 架构治理, 热点分析, 质量保证, 趋势报告, 软件工程工具, 软件架构分析, 输出格式支持, 错误基检测, 静态代码分析