Files
knowledge-governance/internal/governance/version_history.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

272 lines
9.7 KiB
Go
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
package governance
import (
"fmt"
"regexp"
"sort"
"strconv"
"strings"
"time"
)
// 版本记录(「版本记录」页)的领域类型与**版本号口径**。
//
// 口径(主人 2026-10-13 定:只给有证据的版本号):
// - 正式版本:存在**注释 tag** `vX.Y.Z` 指向该提交,且该提交内 CHANGELOG 顶部版本 == X.Y.Z;
// - 开发版本:该提交位于某个正式 tag 之后,且能算出「自该 tag 以来的提交数」⇒ `<主>.<次>.<n>`;
// - 历史提交:证据不足 ⇒ 不下发数字版本号,只给原因(**不补造**)。
//
// 不变量:**完整 SHA 是唯一身份**,版本号不是唯一键;两个提交算出同一个号时两条都保留。
const (
VersionStateVerified = "verified"
VersionStateUnknown = "unknown"
RecordKindRelease = "release"
RecordKindDevelopment = "development"
RecordKindHistorical = "historical"
// 原因码:页面据此显示「版本号未能核验」的具体理由。
ReasonAnnotatedTagMatch = "annotated_tag_and_changelog_top_match"
ReasonLightweightTag = "lightweight_tag"
ReasonChangelogTopMissing = "no_changelog_top"
ReasonChangelogMismatch = "changelog_top_mismatch"
ReasonNoReleaseTag = "no_release_tag_for_commit"
ReasonNoBaseline = "no_baseline"
// ReasonIncompleteGraph:提交图不完整(检出被截断)⇒ 提交数算不准 ⇒ 宁可不给号。
ReasonIncompleteGraph = "shallow_or_incomplete_graph"
// ReasonTagCreatedLater:该版本号对应的 tag 是在**更晚的提交**上打的(不在这个提交的历史里)
// ⇒ 这个提交当时还没有发布基线,不能拿"后来才有的 tag"给它编号。
ReasonTagCreatedLater = "release_tag_created_later"
)
// versionHistorySemver 只认三段十进制、无前导零(与 scripts/check_changelog.py 同口径)。
var versionHistorySemver = regexp.MustCompile(`^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$`)
// releasedHeading 匹配 CHANGELOG 里的已发布版本标题 `## [x.y.z] - …`。
var releasedHeading = regexp.MustCompile(`(?m)^##\s*\[(\d+\.\d+\.\d+)\]\s*$|^##\s*\[(\d+\.\d+\.\d+)\]\s*-`)
// VersionTagEvidence 是一个指向某提交的 tag 及其可核验属性。
type VersionTagEvidence struct {
Name string `json:"name"`
TagSHA string `json:"sha,omitempty"`
Annotated bool `json:"annotated"`
URL string `json:"url,omitempty"`
}
// VersionEvidence 是版本号判定的完整依据(进库的 jsonb,也直接给页面看)。
type VersionEvidence struct {
State string `json:"state"`
Reason string `json:"reason"`
Tags []VersionTagEvidence `json:"tags,omitempty"`
ChangelogTop string `json:"changelog_top,omitempty"`
BaseTag string `json:"base_tag,omitempty"`
CommitsSinceBase *int `json:"commits_since_base,omitempty"`
}
// VersionHistoryCommit 是一条提交记录(版本记录页的列表项)。
type VersionHistoryCommit struct {
RepoKey string
CommitSHA string
Parents []string
CommittedAt time.Time
AuthorDisplay string
Subject string
Body string
VersionLabel string
VersionState string
RecordKind string
ReleaseTags []VersionTagEvidence
ReleaseNotes string
CommitURL string
VersionEvidence VersionEvidence
SnapshotID int64
}
// VersionHistorySyncRun 是一次同步的状态(「同步成功」≠「历史完整」)。
type VersionHistorySyncRun struct {
ID int64
JobID string
Status string
SourceHeadSHA string
StartedAt time.Time
FinishedAt time.Time
LastSuccessAt time.Time
Complete bool
FetchedCount int
ExpectedCount *int
ErrorCode string
ActiveSnapshotID int64
TriggeredBy string
}
// CurrentRunningIdentity 是「当前运行」的判据结果:只认精确匹配,**不猜**。
type CurrentRunningIdentity struct {
State string `json:"state"` // matched | development | unknown
CommitSHA string `json:"commit_sha,omitempty"`
DisplayVersion string `json:"display_version,omitempty"`
MatchedCommitSHA string `json:"matched_commit_sha,omitempty"`
}
// VersionHistoryPage 是列表接口的返回体。
type VersionHistoryPage struct {
Items []VersionHistoryCommit
NextCursor string
HasMore bool
Sync VersionHistorySyncRun
CurrentRunning CurrentRunningIdentity
}
// SemverValid 判断是否为合规三段的正式版本号。
func SemverValid(value string) bool { return versionHistorySemver.MatchString(value) }
// CompareSemver 按主/次/修订比较;任一非法 ⇒ 0(调用方应先校验)。
func CompareSemver(left, right string) int {
lp, ok := semverParts(left)
if !ok {
return 0
}
rp, ok := semverParts(right)
if !ok {
return 0
}
for i := 0; i < 3; i++ {
if lp[i] != rp[i] {
if lp[i] < rp[i] {
return -1
}
return 1
}
}
return 0
}
func semverParts(value string) ([3]int, bool) {
var out [3]int
if !versionHistorySemver.MatchString(value) {
return out, false
}
for i, part := range strings.Split(value, ".") {
n, err := strconv.Atoi(part)
if err != nil {
return out, false
}
out[i] = n
}
return out, true
}
// DecideVersion 按证据判定一个提交的版本号口径。
//
// changelogTop 是该提交内 CHANGELOG 的顶部已发布版本(读不到就空);
// tagsAtCommit 是所有指向该提交的 tag(含注释标记);baseTag/commitsSinceBase
// 来自提交图遍历(最近的正式 tag 与该 tag 以来的提交数),没有就传空/nil。
func DecideVersion(changelogTop string, tagsAtCommit []VersionTagEvidence, baseTag string, commitsSinceBase *int) (label, state, kind string, evidence VersionEvidence) {
evidence = VersionEvidence{State: VersionStateUnknown, Reason: ReasonNoReleaseTag,
Tags: tagsAtCommit, ChangelogTop: changelogTop, BaseTag: baseTag, CommitsSinceBase: commitsSinceBase}
// ① 正式版本:注释 tag + 版本名合法 + 提交内 CHANGELOG 顶部一致。
annotated := make([]VersionTagEvidence, 0, len(tagsAtCommit))
semverTags := make([]VersionTagEvidence, 0, len(tagsAtCommit))
for _, tag := range tagsAtCommit {
if tag.Annotated {
annotated = append(annotated, tag)
}
if SemverValid(strings.TrimPrefix(tag.Name, "v")) {
semverTags = append(semverTags, tag)
}
}
sort.Slice(semverTags, func(i, j int) bool { return semverTags[i].Name < semverTags[j].Name })
for _, tag := range annotated {
version := strings.TrimPrefix(tag.Name, "v")
if !SemverValid(version) {
continue
}
if changelogTop != "" && changelogTop != version {
continue // 该 tag 不合规(版本与提交内记录不一致)⇒ 继续找别的
}
if changelogTop == "" {
evidence.Reason = ReasonChangelogTopMissing
continue
}
return version, VersionStateVerified, RecordKindRelease, VersionEvidence{
State: VersionStateVerified, Reason: ReasonAnnotatedTagMatch, Tags: tagsAtCommit,
ChangelogTop: changelogTop, BaseTag: "v" + version, CommitsSinceBase: commitsSinceBase}
}
// ② 开发版本:基线 tag 存在且能算出「自该 tag 以来的提交数」。
// 口径与 scripts/version.py **完全一致**:基线 = `v<提交内 CHANGELOG 顶部版本>`,
// 号 = `<主>.<次>.<n>`(n=0 时正好等于该版本号本身);两个提交算出同一个号时两条都保留。
if SemverValid(changelogTop) && baseTag != "" && commitsSinceBase != nil && *commitsSinceBase >= 0 {
parts, _ := semverParts(changelogTop)
label := fmt.Sprintf("%d.%d.%d", parts[0], parts[1], *commitsSinceBase)
return label, VersionStateVerified, RecordKindDevelopment, VersionEvidence{
State: VersionStateVerified, Reason: "counted_commits_since_base_tag", Tags: tagsAtCommit,
ChangelogTop: changelogTop, BaseTag: baseTag, CommitsSinceBase: commitsSinceBase}
}
// ③ 历史提交:证据不足 ⇒ 不给号,只给原因(不补造)。
annotatedSemver := 0
for _, tag := range annotated {
if SemverValid(strings.TrimPrefix(tag.Name, "v")) {
annotatedSemver++
}
}
switch {
case len(semverTags) > 0 && annotatedSemver == 0:
evidence.Reason = ReasonLightweightTag
case changelogTop == "":
evidence.Reason = ReasonChangelogTopMissing
case annotatedSemver > 0:
evidence.Reason = ReasonChangelogMismatch
case baseTag == "":
evidence.Reason = ReasonNoBaseline
default:
evidence.Reason = ReasonNoReleaseTag
}
return "", VersionStateUnknown, RecordKindHistorical, evidence
}
// ExtractReleaseNotes 从提交内的 CHANGELOG 文本里取某个已发布版本的整段正文。
//
// 边界口径与 scripts/check_changelog.py 一致:**任意二级标题都是边界**(否则
// `## 能力基线(未发布)` 这类标题会把后文算进上一节)。
func ExtractReleaseNotes(changelog, version string) string {
if changelog == "" || !SemverValid(version) {
return ""
}
lines := strings.Split(changelog, "\n")
start := -1
for i, line := range lines {
if m := releasedHeading.FindStringSubmatch(strings.TrimSpace(line)); m != nil {
if m[1] == version || m[2] == version {
start = i
break
}
}
}
if start < 0 {
return ""
}
var body []string
for _, line := range lines[start+1:] {
if strings.HasPrefix(line, "## ") {
break
}
body = append(body, line)
}
return strings.TrimSpace(strings.Join(body, "\n"))
}
// ChangelogTopVersion 取 CHANGELOG 顶部的已发布版本;没有 ⇒ 空串。
func ChangelogTopVersion(changelog string) string {
for _, line := range strings.Split(changelog, "\n") {
if m := releasedHeading.FindStringSubmatch(strings.TrimSpace(line)); m != nil {
if m[1] != "" {
return m[1]
}
return m[2]
}
}
return ""
}