// Package versionhistory 把「远端 main 可达的提交」+「tag 证据」+「提交内 CHANGELOG」 // 换算成版本记录页要的提交记录。 // // 它**只读、纯计算**:不发网络请求、不写库、不执行任何历史提交里的脚本。版本号口径 // 委托给 internal/governance.DecideVersion,提交数按提交图算(等价 `git rev-list --count ..`), // 与 scripts/version.py 同规则 —— 两处算出的号必须一致。 package versionhistory import ( "sort" "strings" "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 { Message string Name string TagSHA string TargetSHA string Annotated bool } // ChangelogSource 读「某个提交内的 CHANGELOG.md」;读不到返回错误(调用方按"无记录"处理)。 type ChangelogSource func(sha string) (string, error) // DeriveInput 是一次换算的全部输入。 type DeriveInput struct { DeliveryArchive string RepoKey string CommitURLBase string // 形如 "///commit/",由配置拼好,不接受外部传入 TagURLBase string // 形如 "///src/tag/";空则不下发 tag 链接 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] { url := "" if in.TagURLBase != "" { url = in.TagURLBase + tag.Name } evidenceTags = append(evidenceTags, governance.VersionTagEvidence{ Name: tag.Name, TagSHA: tag.TagSHA, Annotated: tag.Annotated, URL: url}) } 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) } else if kind == governance.RecordKindDevelopment { record.ReleaseNotes = governance.ExtractDevelopmentNotes(changelog, label) if record.ReleaseNotes == "" { record.ReleaseNotes = governance.ExtractDevelopmentNotesForCommit(in.DeliveryArchive, label, commit.SHA) } if record.ReleaseNotes == "" { for _, tag := range tagsByTarget[commit.SHA] { if tag.Annotated && tag.Name == "snapshot/v"+label { _, body, found := strings.Cut(tag.Message, "\n\n") if found { record.ReleaseNotes = strings.TrimSpace(body) } break } } } } 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 }