如何为bumblebee贡献代码代码结构、测试规范与Schema版本化规则完全指南【免费下载链接】bumblebeeRead-only developer endpoint scanner for on-disk package, extension, and developer-tool metadata, built to check exposure to known software supply-chain compromises.项目地址: https://gitcode.com/gh_mirrors/bumblebee12/bumblebee想为bumblebee这个供应链暴露扫描器提交第一个 PR 吗本文是一份面向新手的贡献代码完全指南帮你快速看懂 bumblebee 的代码结构、测试规范与Schema 版本化规则三大核心约定。无论你要新增一个生态系统解析器还是升级输出版本掌握这三点就能写出符合项目风格、一次通过的提交。一、bumblebee 是什么先搞懂它扫什么在写代码之前先理解 bumblebee 的定位才能判断你的改动落在哪一层。bumblebee 是一个只读的开发者端点扫描器它只读取本地磁盘上已有的包、扩展和开发工具元数据如锁文件、包管理器安装信息、扩展清单把它们整理成结构化记录并在给定暴露目录时精确匹配已知供应链投毒事件。它有两个关键设计约束直接影响你怎么贡献绝对只读不调用npm ls、pip show、go list等命令也不读源码文件。你新增的解析器同样只能读文件。零第三方运行时依赖只用 Go 标准库go.mod里除了模块声明外几乎没有依赖。这意味着你不能引入任何外部库一切逻辑用标准库实现。约束对贡献者的含义只读扫描解析器只读文件禁止执行包管理器零第三方依赖只能用标准库不引第三方包单一 Go 二进制改动需保证go build一次通过各生态系统支持范围见 README.md 中的 Coverage 表格与 docs/inventory-sources.md。二、贡献前准备克隆仓库与本地构建先克隆仓库并跑通完整构建与测试流程这是所有贡献的起点。git clone https://gitcode.com/gh_mirrors/bumblebee12/bumblebee cd bumblebee go build ./cmd/bumblebee go test ./... go test -race ./... go vet ./... gofmt -l . # 应无任何输出 ./bumblebee selftest⚠️ 需要 Go 1.25。gofmt -l .必须输出为空selftest必须通过——这两项是项目 CI 的硬性门槛。完整的本地开发命令清单官方写得很清楚见 CONTRIBUTING.md。三、代码结构全景四大核心模块如何协作bumblebee 采用典型的入口 → 编排 → 解析 → 输出分层。理解这条数据流你就能定位自己的改动该写在哪。1. 入口层cmd/bumblebee/命令行入口负责解析参数、组装根目录、启动扫描。main.go命令解析与子命令分发roots.go根据 profile 解析扫描根路径selftest.go内嵌 fixture 的端到端自检version.go版本与构建信息2. 编排层internal/scanner/internal/walk/scanner.go扫描编排器负责并发调度、超时控制、把匹配文件分发给各生态系统解析器walk.go有界、感知安全性的文件系统遍历器含符号链接环路保护、敏感目录排除 解析器本身是单线程处理单文件的并发完全由编排器统一掌管——这是贡献解析器时最要记住的一点别在自己的解析器里开并发。3. 解析层internal/ecosystem/你多半在这里动手每个子目录是一个生态系统的解析器结构高度一致生态系统目录主要读取来源npminternal/ecosystem/npm/package-lock.json等PyPIinternal/ecosystem/pypi/*.dist-info/METADATAGo 模块internal/ecosystem/gomod/go.mod、go.sumHomebrewinternal/ecosystem/homebrew/INSTALL_RECEIPT.jsonMCPinternal/ecosystem/mcp/mcp.json等 JSON 配置新增一个生态系统 新建一个子目录 一对xxx.go与xxx_test.go然后在编排器 scanner.go 的导入与分发逻辑中接入。4. 模型与输出层internal/model/internal/output/model.go定义所有记录结构体以及全局唯一的SchemaVersion常量当前为0.2.0output.go把记录写成 NDJSON 到 stdouthttpsink.go可选的 HTTPS 上报通道记录还经过 internal/exposure/暴露目录匹配与 internal/normalize/名称归一化两个横切模块。四、测试规范临时 fixture 优先的实践这是贡献者最容易踩坑的地方。bumblebee 的测试风格统一且克制。核心原则优先用t.TempDir() 内联字符串官方明确要求优先用临时 fixturet.TempDir() 内联字符串而不是提交testdata/文件——除非某个 fixture 被多个测试共用。看一个真实的解析器测试骨架摘自 internal/ecosystem/npm/npm_test.gofunc TestScanLockfileV3ScopedAndUnscoped(t *testing.T) { dir : t.TempDir() // ① 临时目录 lock : filepath.Join(dir, package-lock.json) writeFile(t, lock, {packages: {...}}) // ② 内联字符串写文件 s, got, _ : newCollector() // ③ 构造注入 Emit/Diag 回调的 Scanner if err : s.ScanLockfile(lock, model.Record{}); err ! nil { t.Fatalf(ScanLockfile: %v, err) } // ④ 断言解析出的记录 }三个关键约定注入回调而非真实 IO用newCollector()构造Scanner把Emit、Diag替换成内存切片测试无需落盘。临时目录即弃t.TempDir()自动清理杜绝残留。断言解析结果按nameversion建立 map逐条校验。分层测试单元 集成 自检测试类型文件作用单元测试各xxx_test.go校验单个解析器的输出集成测试scanner_integration_test.go校验完整扫描流程自检selftest.go内嵌 fixture 的端到端冒烟测试提交前必跑go test ./...、go test -race ./...竞态检测、go vet ./...、gofmt -l .。五、Schema 版本化规则为什么不能原地改这是 bumblebee 最容易被忽视、却最严重的规则。输出版本化遵循目录版本化 常量联动两条铁律。规则 1已发布的 schema 绝不允许原地修改Schema 文件按版本目录存放docs/schema/v0.1.0/docs/schema/v0.2.0/任何对docs/schema/version/*.json或线上格式的破坏性变更都属于 breaking change。你必须新建一个版本目录如 docs/schema/v0.3.0/把变更放进去同步bump internal/model/model.go 中的SchemaVersion常量绝不修改已发布目录里的旧文件。// internal/model/model.go const ( SchemaVersion 0.2.0 // 与 docs/schema/版本/ 目录一一对应 )规则 2旧版本目录向后兼容注意 docs/schema/v0.1.0/ 依然保留并被接受。例如 0.1.0 的暴露目录仍被读取只是不支持*通配版本而未来的不支持版本值会被拒绝。你的新版 schema 也要能平滑处理历史版本不能一刀切地丢弃旧数据。规则 3新增暴露目录要先过 schema 校验如果你往 threat_intel/ 加暴露目录提交前必须先用 schema 校验通过python3 -c import json, jsonschema; \ jsonschema.validate(json.load(open(threat_intel/your-catalog.json)), \ json.load(open(docs/schema/v0.2.0/exposure-catalog.schema.json)))参考 docs/schema/v0.2.0/exposure-catalog.schema.json它要求schema_version固定为0.2.0每个条目必须有id、ecosystem、package、versions。六、提交 PR 检查清单最后把官方 CONTRIBUTING.md 的要求浓缩成一张清单提交前逐项打勾PR 小而聚焦重构与行为变更分开提交提交标题遵循约定式提交fix(scope):/feat(scope):/docs:/ci:行为变更已补充或更新测试优先t.TempDir()内联 fixture改了用户可见的 flag / profile / 生态系统 / 输出字段 →同步更新 README.md破坏性 schema 变更 →新建版本目录 bumpSchemaVersion未原地改旧文件go test ./...、go test -race ./...、go vet ./...、gofmt -l .、./bumblebee selftest全部通过安全类问题不走公开 issue改走 SECURITY.md小结贡献 bumblebee 的心法就三句话——代码结构上认准入口→编排→解析→输出四层解析器只读单文件且零第三方依赖测试规范上用t.TempDir() 内联字符串注入回调Schema 版本化上绝不原地改已发布文件新变更进新版本目录并联动 bump 常量。掌握这三点你就能写出干净、一次通过的贡献。【免费下载链接】bumblebeeRead-only developer endpoint scanner for on-disk package, extension, and developer-tool metadata, built to check exposure to known software supply-chain compromises.项目地址: https://gitcode.com/gh_mirrors/bumblebee12/bumblebee创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考