0974d8dfa2
build / build (push) Successful in 57s
按已确认的契约实现(口径见 docs/VERSION_HISTORY.md):
- **版本号口径(只给有证据的)**:注释 tag + tag 指向该提交 + 该提交内 CHANGELOG 顶部三者一致 ⇒ 正式版本;
tag 之后的提交按 `<主>.<次>.<自该 tag 的提交数>` 显示开发号(与 scripts/version.py **同规则**);
证据不足 ⇒ 「历史提交 · 短SHA」+ 原因码,**不补造版本号**。完整 SHA 是唯一身份、版本号不是唯一键
(tag 之后两条并行分支各自的第 1 个提交都算 0.1.1 ⇒ 两条都保留,用短 SHA 区分)。
- **迁移 000046**:version_history_commits(提交记录,主键 repo_key+commit_sha)+ version_history_sync_runs
(同步状态)。快照 = 一次同步:抓完并与 X-Total-Count 对账通过才切换;失败不切换快照、不清空历史、
last_success_at 不动(页面显示"上次同步失败(原因)· 仍展示上次成功数据");「同步成功」≠「历史完整」。
- **只读客户端(匿名,不使用任何凭据)**:白名单 origin + 固定仓库、拒绝任意 URL 与跨主机重定向、
响应上限 5MB / 超时 15s、仅 5xx/429 退避重试(最多 3 次);逐页抓到短页为止;每次全量扫 tag
⇒ 旧提交后补的 tag 会更新既有记录(不新增第二行)。
- **接口**(三个都登记进 api/openapi.yaml):GET /api/v1/build-info(viewer)、
GET /api/v1/version-history(viewer;游标绑定快照,过期返回 409 cursor_expired;不返回伪造 total)、
POST /api/v1/version-history/sync(admin;并发同步复用同一作业,靠 IdempotencyKey)。
- **「当前运行」只认精确匹配**:产物注入的完整 SHA 命中某条记录才标该条;开发构建显式标注"开发构建";
没有可用标识 ⇒ "当前运行版本未知";**不拿最新 main / 最新 tag 顶替**,CI 成功不等于已部署。
- **前端**:一级菜单第 5 项(版本记录)+ 时间线页面(全部/正式/开发/历史四段筛选、正文展开、
加载更多、760px 单列无横向溢出、提交正文与变更记录按纯文本渲染);无打 tag / 发布 / 部署入口。
新增配置(留空即未接线,页面降级):VERSION_HISTORY_GITEA_BASE_URL / _REPO / _ALLOWED_ORIGINS /
_HTTP_TIMEOUT / _MAX_PAGES。
验证:`make verify` 15/15 success(tests-go 578 通过 / 0 失败;tests-web 209 通过 / 0 失败);
新增 Go 用例 30(版本口径与图遍历 12、客户端守卫 6、同步编排 5、接口 7);前端新增 18(组件 10 + 客户端 8);
真实仓库匿名快照拉取(`VERSION_HISTORY_LIVE_BASE_URL=… go test -run TestLiveSyncAgainstRealRepository`):
抓到 113 条与 X-Total-Count 一致、v0.1.0 是注释 tag 且目标与 `git rev-parse v0.1.0^{commit}` 一致、
开发号逐个等于 `git rev-list --count v0.1.0..<sha>`(正式 1 / 开发 22 / 历史 90)。
102 lines
4.4 KiB
Go
102 lines
4.4 KiB
Go
package governance
|
||
|
||
import "testing"
|
||
|
||
func tag(name string, annotated bool) VersionTagEvidence {
|
||
return VersionTagEvidence{Name: name, TagSHA: "tag-" + name, Annotated: annotated}
|
||
}
|
||
|
||
func intPtr(value int) *int { return &value }
|
||
|
||
func TestDecideVersionReleaseRequiresAnnotatedTagAndChangelogTop(t *testing.T) {
|
||
cases := []struct {
|
||
name string
|
||
changelogTop string
|
||
tags []VersionTagEvidence
|
||
wantLabel string
|
||
wantKind string
|
||
wantReason string
|
||
}{
|
||
{"注释 tag + 顶部一致 ⇒ 正式版本", "0.1.0", []VersionTagEvidence{tag("v0.1.0", true)},
|
||
"0.1.0", RecordKindRelease, ReasonAnnotatedTagMatch},
|
||
{"轻量 tag 指向该提交 ⇒ 不算正式版本", "0.1.0", []VersionTagEvidence{tag("v0.1.0", false)},
|
||
"", RecordKindHistorical, ReasonLightweightTag},
|
||
{"有版本但无 tag ⇒ 不算正式版本", "0.1.0", nil, "", RecordKindHistorical, ReasonNoBaseline},
|
||
{"注释 tag 与提交内顶部不一致 ⇒ 不算正式版本", "0.1.1", []VersionTagEvidence{tag("v0.1.0", true)},
|
||
"", RecordKindHistorical, ReasonChangelogMismatch},
|
||
{"非三段版本名的 tag ⇒ 不算正式版本", "0.1.0", []VersionTagEvidence{tag("v0.1", true)},
|
||
"", RecordKindHistorical, ReasonNoBaseline},
|
||
}
|
||
for _, tc := range cases {
|
||
label, state, kind, evidence := DecideVersion(tc.changelogTop, tc.tags, "", nil)
|
||
if label != tc.wantLabel || kind != tc.wantKind {
|
||
t.Fatalf("%s:label=%q kind=%q,期望 %q/%q(reason=%s)", tc.name, label, kind, tc.wantLabel, tc.wantKind, evidence.Reason)
|
||
}
|
||
if evidence.Reason != tc.wantReason {
|
||
t.Fatalf("%s:reason=%q,期望 %q", tc.name, evidence.Reason, tc.wantReason)
|
||
}
|
||
if tc.wantKind == RecordKindHistorical && state != VersionStateUnknown {
|
||
t.Fatalf("%s:历史提交必须是 unknown,得到 %q", tc.name, state)
|
||
}
|
||
}
|
||
}
|
||
|
||
func TestDecideVersionDevelopmentUsesBaseTagCount(t *testing.T) {
|
||
label, state, kind, evidence := DecideVersion("0.1.0", nil, "v0.1.0", intPtr(12))
|
||
if label != "0.1.12" || kind != RecordKindDevelopment || state != VersionStateVerified {
|
||
t.Fatalf("开发号计算错:%q/%q/%q", label, kind, state)
|
||
}
|
||
if evidence.BaseTag != "v0.1.0" || evidence.CommitsSinceBase == nil || *evidence.CommitsSinceBase != 12 {
|
||
t.Fatalf("依据不完整:%+v", evidence)
|
||
}
|
||
// 恰在发布提交上(0 个提交)⇒ 号就是该版本号
|
||
label, _, kind, _ = DecideVersion("0.1.0", nil, "v0.1.0", intPtr(0))
|
||
if label != "0.1.0" || kind != RecordKindDevelopment {
|
||
t.Fatalf("0 个提交时应等于版本号本身,得到 %q/%q", label, kind)
|
||
}
|
||
// 图不完整 ⇒ 不给号
|
||
label, _, kind, _ = DecideVersion("0.1.0", nil, "", nil)
|
||
if label != "" || kind != RecordKindHistorical {
|
||
t.Fatalf("无基线时必须不下发号,得到 %q/%q", label, kind)
|
||
}
|
||
}
|
||
|
||
func TestDecideVersionKeepsSameNumberForDifferentCommits(t *testing.T) {
|
||
// 两个提交算出同一个号:判定层不合并、不去重(唯一身份是 SHA)
|
||
first, _, _, _ := DecideVersion("0.1.0", nil, "v0.1.0", intPtr(3))
|
||
second, _, _, _ := DecideVersion("0.1.0", nil, "v0.1.0", intPtr(3))
|
||
if first != second || first != "0.1.3" {
|
||
t.Fatalf("同号应各自保留:%q / %q", first, second)
|
||
}
|
||
}
|
||
|
||
func TestChangelogTopAndReleaseNotes(t *testing.T) {
|
||
changelog := "# Changelog\n\n## [Unreleased]\n\n### Added\n\n- 新\n\n" +
|
||
"## [0.2.0] - 2026-10-13\n\n### Changed\n\n- **破坏性**:接口下线\n\n" +
|
||
"## [0.1.0] - 2026-10-01\n\n### Added\n\n- 旧\n"
|
||
if top := ChangelogTopVersion(changelog); top != "0.2.0" {
|
||
t.Fatalf("顶部版本 = %q,期望 0.2.0", top)
|
||
}
|
||
notes := ExtractReleaseNotes(changelog, "0.2.0")
|
||
if notes != "### Changed\n\n- **破坏性**:接口下线" {
|
||
t.Fatalf("0.2.0 段落 = %q", notes)
|
||
}
|
||
if ExtractReleaseNotes(changelog, "9.9.9") != "" {
|
||
t.Fatal("不存在的版本必须返回空,不许猜")
|
||
}
|
||
// 不带方括号的二级标题也是边界(与 check_changelog 同口径)
|
||
boundary := "# Changelog\n\n## [0.1.0] - 2026-10-01\n\n### Added\n\n- 甲\n\n## 能力基线(未发布)\n\n- 乙\n"
|
||
if notes := ExtractReleaseNotes(boundary, "0.1.0"); notes != "### Added\n\n- 甲" {
|
||
t.Fatalf("边界算错:%q", notes)
|
||
}
|
||
}
|
||
|
||
func TestSemverHelpers(t *testing.T) {
|
||
if !SemverValid("0.1.0") || SemverValid("01.1.0") || SemverValid("0.1") || SemverValid("v0.1.0") {
|
||
t.Fatal("三段无前导零校验不对")
|
||
}
|
||
if CompareSemver("0.10.0", "0.9.0") != 1 || CompareSemver("1.0.0", "1.0.0") != 0 || CompareSemver("0.1.0", "0.2.0") != -1 {
|
||
t.Fatal("版本比较不对")
|
||
}
|
||
}
|