4d43a9386a
build / build (push) Successful in 1m5s
真实数据发现(本机 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 通过。
272 lines
9.7 KiB
Go
272 lines
9.7 KiB
Go
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 ""
|
||
}
|