Files
knowledge-governance/internal/versionhistory/rules.go
T
姚章浩 4d43a9386a
build / build (push) Successful in 1m5s
fix(version-history): tag 之前的提交不再被编号 + 部署脚本注入构建身份
真实数据发现(本机 p1 实例第一次同步后核对):
- **缺陷**:tag `v0.1.0` 之前的 20 个提交,提交内 CHANGELOG 顶部**也已经**是 0.1.0(旧分支遗留条目),
  而它们的祖先集合被那个**更晚才打**的 tag 全覆盖 ⇒ 按提交数算得 0 ⇒ 被错标成「0.1.0 开发版」。
  它们的正确判定是「历史提交」:那个 tag 是后来才打的,当时还没有发布基线。
- **修复**:基线 tag 必须是该提交的**祖先(或就是该提交)**,否则不给号;新增原因码
  `release_tag_created_later`(页面文案:'该版本是在更晚的提交上发布的 —— 这个提交当时还没有 tag')。
  回归用例两条:`TestDeriveVersionsDoesNotNumberCommitsThatPredateTheTag`、
  `TestDeriveVersionsSideBranchWithoutTagStaysHistorical`(不含 tag 的侧分支同样不给号)。
- **部署脚本注入构建身份**:`scripts/deploy-api-web.sh` 原先不传 `-ldflags -X`,产物 `CommitSHA=unknown`
  ⇒ 页面只能显示"当前运行版本未知"(契约上诚实,但没用)。现在按 `scripts/version.py --identity`
  (唯一来源,与 Makefile/CI 同规则)注入 VERSION/RELEASE_VERSION/BUILD_KIND/COMMITS_SINCE_RELEASE/
  COMMIT_SHA/BUILD_TIME;取不到身份**拒绝继续**(宁可不上线,也不上线一个认不出自己的产物),
  并在收尾核对注入的 SHA 真的进了产物。
- compose.yaml:把 VERSION_HISTORY_* 五项接进应用环境(api/worker 共享锚点),留空即未接线。

验证:真实仓库复验(114 条对账一致)⇒ 正式 1 / 开发 4 / 历史 109(原来错的 19 条现在都是
`release_tag_created_later`);p1 实例重新同步后当前快照分布一致,带号的记录只剩 1 正式 + 4 开发
(含真实存在的「同号不同 SHA」:950c1b4 与 3a1d32d 都是 0.1.1,各占一行);
make verify 15/15 success;前端 18 用例 + typecheck 通过。
2026-10-14 10:00:27 +08:00

204 lines
6.3 KiB
Go

// Package versionhistory 把「远端 main 可达的提交」+「tag 证据」+「提交内 CHANGELOG」
// 换算成版本记录页要的提交记录。
//
// 它**只读、纯计算**:不发网络请求、不写库、不执行任何历史提交里的脚本。版本号口径
// 委托给 internal/governance.DecideVersion,提交数按提交图算(等价 `git rev-list --count <tag>..<sha>`),
// 与 scripts/version.py 同规则 —— 两处算出的号必须一致。
package versionhistory
import (
"sort"
"time"
"knowledge-governance/internal/governance"
)
// RawCommit 是一条从 Gitea 读回的提交(只保留展示与判版本所需的字段)。
type RawCommit struct {
SHA string
Parents []string
CommittedAt time.Time
AuthorDisplay string
Subject string
Body string
}
// RawTag 是一个 tag 及其可核验属性;Annotated=false 表示轻量 tag(不算正式版本的证据)。
type RawTag struct {
Name string
TagSHA string
TargetSHA string
Annotated bool
}
// ChangelogSource 读「某个提交内的 CHANGELOG.md」;读不到返回错误(调用方按"无记录"处理)。
type ChangelogSource func(sha string) (string, error)
// DeriveInput 是一次换算的全部输入。
type DeriveInput struct {
RepoKey string
CommitURLBase string // 形如 "<origin>/<owner>/<repo>/commit/",由配置拼好,不接受外部传入
Commits []RawCommit
Tags []RawTag
Changelog ChangelogSource
SnapshotID int64
}
// DeriveResult 是换算结果。
type DeriveResult struct {
Records []governance.VersionHistoryCommit
GraphComplete bool
MissingParents []string
}
// DeriveVersions 逐提交判定版本号(含合并提交与侧分支提交;不展示任何未推送的本地提交,
// 因为输入本身就是远端 main 可达集合)。
func DeriveVersions(in DeriveInput) DeriveResult {
bySHA := make(map[string]RawCommit, len(in.Commits))
for _, commit := range in.Commits {
bySHA[commit.SHA] = commit
}
missing := map[string]bool{}
ancestors := make(map[string]map[string]struct{}, len(in.Commits))
var walk func(sha string) map[string]struct{}
walk = func(sha string) map[string]struct{} {
if set, ok := ancestors[sha]; ok {
return set
}
set := map[string]struct{}{sha: {}}
ancestors[sha] = set // 先占位,DAG 不会有环
commit, ok := bySHA[sha]
if !ok {
return set
}
for _, parent := range commit.Parents {
if _, known := bySHA[parent]; !known {
missing[parent] = true
continue
}
for item := range walk(parent) {
set[item] = struct{}{}
}
}
return set
}
for _, commit := range in.Commits {
walk(commit.SHA)
}
tagsByTarget := map[string][]RawTag{}
tagByName := map[string]RawTag{}
for _, tag := range in.Tags {
tagsByTarget[tag.TargetSHA] = append(tagsByTarget[tag.TargetSHA], tag)
if _, exists := tagByName[tag.Name]; !exists {
tagByName[tag.Name] = tag
}
}
changelogCache := map[string]string{}
readChangelog := func(sha string) string {
if text, ok := changelogCache[sha]; ok {
return text
}
text := ""
if in.Changelog != nil {
if loaded, err := in.Changelog(sha); err == nil {
text = loaded
}
}
changelogCache[sha] = text
return text
}
graphComplete := len(missing) == 0
result := DeriveResult{GraphComplete: graphComplete}
for sha := range missing {
result.MissingParents = append(result.MissingParents, sha)
}
sort.Strings(result.MissingParents)
records := make([]governance.VersionHistoryCommit, 0, len(in.Commits))
for _, commit := range in.Commits {
changelog := readChangelog(commit.SHA)
top := governance.ChangelogTopVersion(changelog)
baseTagName := ""
var sinceBase *int
tagCreatedLater := false
if governance.SemverValid(top) {
candidate := "v" + top
if base, exists := tagByName[candidate]; exists {
own, ownKnown := ancestors[commit.SHA]
_, tagIsAncestor := own[base.TargetSHA]
switch {
case !graphComplete:
// tag 存在但图不完整 ⇒ 不给号(宁可没号,也不报错号)
baseTagName = candidate
case !ownKnown:
// 连自己的祖先都给不出 ⇒ 不给号
case !tagIsAncestor:
// **该 tag 是更晚才打在这个提交之后的**:这个提交当时还没有发布基线。
// (提交数在这里算会得到 0 —— 因为它的祖先全被那个更晚的 tag 覆盖 —— 拿它编号是错的。)
tagCreatedLater = true
default:
baseSet := ancestors[base.TargetSHA]
count := 0
for item := range own {
if _, inBase := baseSet[item]; !inBase {
count++
}
}
baseTagName = candidate
sinceBase = &count
}
}
}
evidenceTags := make([]governance.VersionTagEvidence, 0, len(tagsByTarget[commit.SHA]))
for _, tag := range tagsByTarget[commit.SHA] {
evidenceTags = append(evidenceTags, governance.VersionTagEvidence{
Name: tag.Name, TagSHA: tag.TagSHA, Annotated: tag.Annotated})
}
sort.Slice(evidenceTags, func(i, j int) bool { return evidenceTags[i].Name < evidenceTags[j].Name })
label, state, kind, evidence := governance.DecideVersion(top, evidenceTags, baseTagName, sinceBase)
switch {
case label != "":
case !graphComplete:
evidence.Reason = governance.ReasonIncompleteGraph
case tagCreatedLater:
evidence.Reason = governance.ReasonTagCreatedLater
}
record := governance.VersionHistoryCommit{
RepoKey: in.RepoKey,
CommitSHA: commit.SHA,
Parents: commit.Parents,
CommittedAt: commit.CommittedAt,
AuthorDisplay: commit.AuthorDisplay,
Subject: commit.Subject,
Body: commit.Body,
VersionLabel: label,
VersionState: state,
RecordKind: kind,
ReleaseTags: evidenceTags,
CommitURL: in.CommitURLBase + commit.SHA,
VersionEvidence: evidence,
SnapshotID: in.SnapshotID,
}
if kind == governance.RecordKindRelease {
record.ReleaseNotes = governance.ExtractReleaseNotes(changelog, label)
}
records = append(records, record)
}
// 最新在上;同一提交时间用 SHA 兜底 ⇒ 排序确定,分页不重不漏。
sort.SliceStable(records, func(i, j int) bool {
if !records[i].CommittedAt.Equal(records[j].CommittedAt) {
return records[i].CommittedAt.After(records[j].CommittedAt)
}
return records[i].CommitSHA > records[j].CommitSHA
})
result.Records = records
return result
}