This is an automated email from the ASF dual-hosted git repository. AlexStocks pushed a commit to branch codex/fix-sonar-cli-template-locks in repository https://gitbox.apache.org/repos/asf/dubbo-go.git
commit e1196fc39a1d26ae96eeb1a8208ff423967f8b3d Author: Xin.Zh <[email protected]> AuthorDate: Sat Aug 1 17:29:02 2026 +0800 Document the Sonar CLI lockfile repair Define the evidence-backed scope, dependency checksum design, TDD regression, Linux verification, and release boundary for restoring generated-project go.sum files. Constraint: Preserve the dynamic protobuf generation architecture and target only the two CLI scaffolds. Confidence: high Scope-risk: narrow Tested: git diff --check; specification placeholder and scope scan. Not-tested: Implementation tests are deferred to the execution plan. Co-authored-by: OmX <[email protected]> Signed-off-by: Xin.Zh <[email protected]> --- .../2026-08-01-fix-sonar-cli-template-locks.md | 101 +++++++++++++++++++++ ...26-08-01-fix-sonar-cli-template-locks-design.md | 48 ++++++++++ 2 files changed, 149 insertions(+) diff --git a/docs/superpowers/plans/2026-08-01-fix-sonar-cli-template-locks.md b/docs/superpowers/plans/2026-08-01-fix-sonar-cli-template-locks.md new file mode 100644 index 000000000..873a248d8 --- /dev/null +++ b/docs/superpowers/plans/2026-08-01-fix-sonar-cli-template-locks.md @@ -0,0 +1,101 @@ +# CLI 模板依赖锁修复实现计划 + +> **面向 AI 代理的工作者：** 必需子技能：使用 superpowers:executing-plans 逐任务实现此计划。步骤使用复选框（`- [ ]`）语法跟踪进度。 + +**目标：** 恢复 `dubbogo-cli` 生成项目的完整 `go.sum`，清除主分支 Sonar `text:S8566` 新代码漏洞。 + +**架构：** application 与 sample generator 复用一个静态 checksum 源，并分别生成 `go.sum`；golden template 保存同一内容。现有动态协议源码生成和 `make test` 的 tidy 链路保持不变。 + +**技术栈：** Go 1.25、Go Modules、GNU Make、SonarQube Cloud、GitHub Actions。 + +--- + +## 文件职责与变更结构 + +- `tools/dubbogo-cli/cmd/gen_test.go`：从公开 generator 入口验证新项目立即包含依赖 checksum。 +- `tools/dubbogo-cli/generator/internal/scaffold/gosum.go`：application 与 sample generator 共用的完整 checksum 内容。 +- `tools/dubbogo-cli/generator/application/gomod.go`：为 newApp 注册 `go.sum` 输出。 +- `tools/dubbogo-cli/generator/sample/mod.go`：为 newDemo 注册 `go.sum` 输出。 +- `tools/dubbogo-cli/cmd/testGenCode/template/newApp/go.sum`：newApp golden checksum。 +- `tools/dubbogo-cli/cmd/testGenCode/template/newDemo/go.sum`：newDemo golden checksum。 + +### 任务 1：建立 Sonar 回归红灯 + +- [ ] **步骤 1：增加行为测试** + +在 `tools/dubbogo-cli/cmd/gen_test.go` 添加一个 table-driven 测试，依次调用 `application.Generate` 和 `sample.Generate`，读取生成目录的 `go.sum`，断言文件非空，并包含： + +```text +dubbo.apache.org/dubbo-go/v3 v3.3.1 +google.golang.org/protobuf v1.34.2 +``` + +- [ ] **步骤 2：运行测试确认正确失败** + +运行： + +```powershell +go test ./cmd -run '^TestGeneratedProjectsIncludeDependencyLocks$' -count=1 -v +``` + +预期：`newApp` 和 `newDemo` 子测试因生成目录缺少 `go.sum` 而失败；失败不能来自编译、路径拼写或依赖下载。 + +### 任务 2：恢复完整 dependency checksum 输出 + +- [ ] **步骤 1：生成当前依赖图的完整 go.sum** + +在隔离 probe 中生成 fresh newApp/newDemo，执行协议生成和 `go mod tidy`，确认两者的 `go.sum` 完全相同。不得直接复用依赖版本已经变化的旧 checksum。 + +- [ ] **步骤 2：恢复共享 checksum 与 generator 注册** + +创建 `generator/internal/scaffold/gosum.go`，并在 application/sample 的模块文件注册逻辑中新增 `go.sum` file generator。 + +- [ ] **步骤 3：恢复两个 golden go.sum** + +将同一份完整 checksum 写入 newApp 和 newDemo golden template。 + +- [ ] **步骤 4：运行回归测试确认绿灯** + +运行： + +```powershell +go test ./cmd -run '^TestGeneratedProjectsIncludeDependencyLocks$|^TestNewApp$|^TestNewDemo$' -count=1 -v +``` + +预期：三个顶层测试及所有子测试通过。 + +### 任务 3：验证并交付 PR + +- [ ] **步骤 1：验证测试质量** + +按 test-guard 检查新增测试只验证公开行为、没有 mock、两个 generator 变体使用同一 table-driven 测试，并明确对应 Sonar 回归。 + +- [ ] **步骤 2：执行模块验证** + +运行： + +```powershell +go test ./... -count=1 +go vet ./... +``` + +工作目录：`tools/dubbogo-cli`。预期全部退出 0。 + +- [ ] **步骤 3：执行 Linux/WSL 生成项目验证** + +运行 CI 等价的生成项目 E2E，并对 fresh newApp/newDemo 分别执行 `go mod tidy -diff`。预期退出 0，tidy 无差异。 + +- [ ] **步骤 4：执行仓库状态和差异门禁** + +运行： + +```powershell +git diff --check +git status --short +``` + +预期：无空白错误；只包含设计、计划、回归测试、共享 checksum、两个 generator 注册和两个 golden `go.sum`。 + +- [ ] **步骤 5：提交、审查、推送和创建 PR** + +使用带 Signed-off-by 的 Lore 格式提交；请求独立代码审查，修复 Critical/Important 反馈；重新验证后推送 `codex/fix-sonar-cli-template-locks`，创建以 `develop` 为 Base 的 PR，并复检 PR Head、Diff 文件、checks 和 Sonar 状态。 diff --git a/docs/superpowers/specs/2026-08-01-fix-sonar-cli-template-locks-design.md b/docs/superpowers/specs/2026-08-01-fix-sonar-cli-template-locks-design.md new file mode 100644 index 000000000..42441968e --- /dev/null +++ b/docs/superpowers/specs/2026-08-01-fix-sonar-cli-template-locks-design.md @@ -0,0 +1,48 @@ +# 修复 CLI 模板 Sonar 依赖锁告警设计 + +## 背景 + +`main@cdda54be1f353e372a80940729cdb380702c325e` 的 SonarQube Cloud 分析报告两个 `text:S8566` 漏洞： + +- `tools/dubbogo-cli/cmd/testGenCode/template/newApp/go.mod` +- `tools/dubbogo-cli/cmd/testGenCode/template/newDemo/go.mod` + +两个模板在 #3585/#3587 的 scaffold 重构中删除了 `go.sum`。生成项目的 `make test` 会先运行 `go mod tidy`，因此正常编译路径仍可工作，但刚生成的项目缺少已提交的依赖 checksum，导致主分支新代码安全评级降为 C。 + +## 目标 + +1. `application.Generate` 与 `sample.Generate` 生成的项目立即包含完整、非空的 `go.sum`。 +2. 两个 golden template 保存与 generator 输出一致的 `go.sum`，使 Sonar 能在仓库树中识别锁文件。 +3. 保留 #3585/#3587 的动态协议源码架构；不恢复内嵌的 `*.pb.go`、`*.triple.go` 或其他已删除生成文件。 +4. 生成项目运行 `go mod tidy -diff` 时不需要修正依赖 checksum。 + +## 方案 + +恢复一个由 application 与 sample generator 共用的 checksum 源。两个 generator 在写入 `go.mod` 的同时写入相同的 `go.sum`，两个 golden template 保存相同内容。 + +checksum 必须由当前模板的 `go.mod` 和实际生成后的协议源码通过 Go 1.25/Linux 的 `go mod tidy` 生成，不能沿用旧版本依赖图。`make test` 仍保留 `proto-gen -> tidy -> go test`，用于后续依赖或生成代码发生变化时校正模块元数据。 + +不采用 Sonar 排除或误报标记，因为生成项目确实应携带可审计的依赖 checksum；不采用在 generator 执行期间调用 `go mod tidy`，避免生成命令新增网络、Go 工具链和外部进程依赖。 + +## 测试设计 + +先增加 `TestGeneratedProjectsIncludeDependencyLocks`： + +1. 通过公开的 `application.Generate` 和 `sample.Generate` 分别生成项目到 `t.TempDir()`。 +2. 读取生成目录中的 `go.sum`。 +3. 断言文件非空，并包含当前两个直接依赖版本的 checksum 记录。 + +该测试在当前 Head 上应因 `go.sum` 不存在而失败。实现后，同一测试应通过；现有 `TestNewApp`/`TestNewDemo` 继续验证 generator 与 golden template 的完整文件集合和逐字节内容一致。 + +补充验证： + +- `go test ./cmd -run '^TestGeneratedProjectsIncludeDependencyLocks$' -count=1 -v` +- `go test ./... -count=1`，工作目录为 `tools/dubbogo-cli` +- 对 fresh `newApp` 和 `newDemo` 执行 `go mod tidy -diff` +- 在 Linux/WSL 执行生成项目 E2E `make test` +- `go vet ./...` +- `git diff --check` + +## 发布边界 + +修复通过正常 PR 合入 `develop`。不修改、重打或重新发布 `v3.3.2`；根模块发布 ZIP 不包含 `tools/dubbogo-cli` 嵌套模块，本修复面向后续主分支质量状态和新的 CLI 源码版本。
