Gitlink
/
gitlink-cli
0
0
Fork 49
Code Issues Pull Requests 11 Packages Projects Releases 10 Wiki Activity

feat(workflow): 增强 PR 队列等待与责任信号

This commit is contained in:
Mengz 2026-07-20 17:33:53 +08:00
parent fe16be4a64
commit 914df4b06a
5 changed files with 264 additions and 44 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
doc/changes/workflow-review-queue-delta.md
View File

@ -25,10 +25,14 @@ gitlink-cli workflow +review-queue \
`changes` 中的条目按 PR 编号匹配；没有编号的本地输入才回退到规范化标题。比较只读本地快照，不会写入远程仓库。
## 等待效率信号
队列结果现在同时记录 `created_at`、`updated_at`、`age_hours`、`waiting_hours`、`stale`、`review_state`、`reviewers` 和 `waiting_on`。通过 `--as-of` 可固定计算时刻，通过 `--stale-after-hours` 可按仓库 SLA 调整阈值；默认阈值为 72 小时。`waiting_on` 只根据明确的 review 状态推断作者、reviewer 或维护者，不会把未知状态伪装成责任归属。等待达到阈值的条目会增加队列优先级，并在 Markdown 中单独显示 SLA 摘要。
## 兼容性与验证
- 不传 `--previous` 时原有输出和优先级排序保持不变。
- `changes` 是可选 JSON 字段，旧消费者可以忽略。
- 非法快照会给出明确错误，不会静默生成不完整差异。
- `go test ./shortcuts/workflow -run 'TestCompareReviewQueue|TestReadReviewQueueResult|TestRenderReviewQueueMarkdownIncludesChanges' -count=1` 通过。
- `go test ./shortcuts/workflow -run 'TestAnalyzeReviewQueue|TestCompareReviewQueue|TestReadReviewQueue|TestFetchReviewQueue|TestRenderReviewQueue' -count=1` 通过。
- `go build ./...` 和 `git diff --check` 通过。

75
shortcuts/workflow/pr_fetch.go
View File

@ -173,22 +173,26 @@ func normalizePRSummaryItem(item map[string]interface{}) (PRSummaryInput, bool)
firstPRTime(item, "last_updated_at", "lastUpdatedAt"),
firstPRTime(item, "last_activity_at", "lastActivityAt"),
)
reviewState := firstPRString(item, "review_state", "review_status", "reviewer_state", "review_decision")
reviewers := firstPRStringList(item, "reviewers", "reviewer", "requested_reviewers", "reviewer_logins")
additions := firstPRInt(item, "additions", "additions_count")
deletions := firstPRInt(item, "deletions", "deletions_count")
return PRSummaryInput{
Number: number,
IssueID: issueID,
Title: title,
Author: author,
State: state,
BaseBranch: base,
HeadBranch: head,
CreatedAt: createdAt,
UpdatedAt: updatedAt,
Body: body,
Additions: additions,
Deletions: deletions,
Number: number,
IssueID: issueID,
Title: title,
Author: author,
State: state,
BaseBranch: base,
HeadBranch: head,
CreatedAt: createdAt,
UpdatedAt: updatedAt,
ReviewState: reviewState,
Reviewers: reviewers,
Body: body,
Additions: additions,
Deletions: deletions,
}, true
}
@ -264,6 +268,53 @@ func firstPRString(item map[string]interface{}, keys ...string) string {
return ""
}
func firstPRStringList(item map[string]interface{}, keys ...string) []string {
for _, key := range keys {
value, ok := item[key]
if !ok {
continue
}
values := normalizePRStringList(value)
if len(values) > 0 {
return values
}
}
return nil
}
func normalizePRStringList(value interface{}) []string {
values := []string{}
appendValue := func(raw interface{}) {
if item, ok := raw.(map[string]interface{}); ok {
for _, key := range []string{"login", "username", "name", "handle"} {
if name := strings.TrimSpace(apiString(item[key])); name != "" {
values = append(values, name)
return
}
}
return
}
for _, part := range strings.FieldsFunc(apiString(raw), func(r rune) bool { return r == ',' || r == ';' || r == ' ' }) {
if name := strings.TrimSpace(part); name != "" {
values = append(values, name)
}
}
}
switch typed := value.(type) {
case []interface{}:
for _, item := range typed {
appendValue(item)
}
case []string:
for _, item := range typed {
appendValue(item)
}
default:
appendValue(value)
}
return uniqueStrings(values)
}
func firstPRInt(item map[string]interface{}, keys ...string) int {
for _, key := range keys {
if value, ok := item[key]; ok {

2
shortcuts/workflow/pr_summary.go
View File

@ -41,6 +41,8 @@ type PRSummaryInput struct {
HeadBranch string `json:"head_branch"`
CreatedAt time.Time `json:"created_at,omitempty"`
UpdatedAt time.Time `json:"updated_at,omitempty"`
ReviewState string `json:"review_state,omitempty"`
Reviewers []string `json:"reviewers,omitempty"`
Body string `json:"body,omitempty"`
ChangedFiles []PRChangedFile `json:"changed_files"`
Commits []PRCommit `json:"commits"`

169
shortcuts/workflow/review_queue.go
View File

@ -9,15 +9,18 @@ import (
"sort"
"strings"
"text/tabwriter"
"time"
"github.com/gitlink-org/gitlink-cli/cmd/cmdutil"
"github.com/gitlink-org/gitlink-cli/shortcuts/common"
)
type ReviewQueueInput struct {
Repository string `json:"repository"`
PullRequests []PRSummaryInput `json:"pull_requests"`
Source string `json:"source"`
Repository string `json:"repository"`
PullRequests []PRSummaryInput `json:"pull_requests"`
Source string `json:"source"`
AsOf time.Time `json:"as_of,omitempty"`
StaleAfterHours int `json:"stale_after_hours,omitempty"`
}
type ReviewQueueResult struct {
@ -30,6 +33,8 @@ type ReviewQueueResult struct {
TopFocus []string `json:"top_focus"`
Recommendations []string `json:"recommendations"`
Source string `json:"source"`
AsOf time.Time `json:"as_of"`
StaleAfterHours int `json:"stale_after_hours"`
Changes *ReviewQueueDelta `json:"changes,omitempty"`
}
@ -55,22 +60,31 @@ type ReviewQueueDeltaItem struct {
}
type ReviewQueueItem struct {
Rank int `json:"rank"`
Number int `json:"number,omitempty"`
Title string `json:"title"`
Author string `json:"author,omitempty"`
State string `json:"state,omitempty"`
ChangeType string `json:"change_type"`
RiskLevel string `json:"risk_level"`
Priority string `json:"priority"`
PriorityScore int `json:"priority_score"`
ChangedFiles int `json:"changed_files"`
Commits int `json:"commits"`
Additions int `json:"additions"`
Deletions int `json:"deletions"`
Reasons []string `json:"reasons"`
SuggestedAction string `json:"suggested_action"`
ReviewFocus []string `json:"review_focus,omitempty"`
Rank int `json:"rank"`
Number int `json:"number,omitempty"`
Title string `json:"title"`
Author string `json:"author,omitempty"`
State string `json:"state,omitempty"`
ChangeType string `json:"change_type"`
RiskLevel string `json:"risk_level"`
Priority string `json:"priority"`
PriorityScore int `json:"priority_score"`
ChangedFiles int `json:"changed_files"`
Commits int `json:"commits"`
Additions int `json:"additions"`
Deletions int `json:"deletions"`
Reasons []string `json:"reasons"`
SuggestedAction string `json:"suggested_action"`
ReviewFocus []string `json:"review_focus,omitempty"`
CreatedAt time.Time `json:"created_at,omitempty"`
UpdatedAt time.Time `json:"updated_at,omitempty"`
AgeHours int `json:"age_hours,omitempty"`
WaitingHours int `json:"waiting_hours,omitempty"`
Stale bool `json:"stale"`
ReviewState string `json:"review_state,omitempty"`
Reviewers []string `json:"reviewers,omitempty"`
ReviewerCount int `json:"reviewer_count"`
WaitingOn string `json:"waiting_on,omitempty"`
}
func newReviewQueueShortcut() *common.Shortcut {
@ -83,6 +97,8 @@ func newReviewQueueShortcut() *common.Shortcut {
{Name: "state", Usage: "Remote pull request state to fetch", Default: "open"},
{Name: "page", Short: "p", Usage: "Remote pull request page", Default: "1"},
{Name: "limit", Short: "l", Usage: "Maximum pull requests to include", Default: "30"},
{Name: "as-of", Usage: "Reference time for age and SLA calculations (RFC3339; defaults to now)"},
{Name: "stale-after-hours", Usage: "Mark PRs stale after this many hours without an update", Default: "72"},
{Name: "lang", Usage: "Output language: en or zh-CN", Default: langEN},
},
Run: runReviewQueue,
@ -117,6 +133,17 @@ func runReviewQueue(ctx *common.RuntimeContext) error {
}
func collectReviewQueueInput(ctx *common.RuntimeContext) (ReviewQueueInput, error) {
asOf, err := parseReviewQueueAsOf(ctx.Arg("as-of"))
if err != nil {
return ReviewQueueInput{}, err
}
staleAfterHours, err := parseIntArg(ctx.Arg("stale-after-hours"), 72, "stale-after-hours")
if err != nil {
return ReviewQueueInput{}, err
}
if staleAfterHours <= 0 {
return ReviewQueueInput{}, fmt.Errorf("stale-after-hours must be greater than zero")
}
if path := strings.TrimSpace(ctx.Arg("from")); path != "" {
input, err := readReviewQueueInput(path)
if err != nil {
@ -125,6 +152,12 @@ func collectReviewQueueInput(ctx *common.RuntimeContext) (ReviewQueueInput, erro
if strings.TrimSpace(input.Source) == "" {
input.Source = "local-json"
}
if input.AsOf.IsZero() {
input.AsOf = asOf
}
if input.StaleAfterHours <= 0 {
input.StaleAfterHours = staleAfterHours
}
return input, nil
}
limit, err := parseIntArg(ctx.Arg("limit"), 30, "limit")
@ -144,12 +177,25 @@ func collectReviewQueueInput(ctx *common.RuntimeContext) (ReviewQueueInput, erro
return ReviewQueueInput{}, err
}
return ReviewQueueInput{
Repository: fmt.Sprintf("%s/%s", owner, repo),
PullRequests: prs,
Source: "remote-read-only-fetch",
Repository: fmt.Sprintf("%s/%s", owner, repo),
PullRequests: prs,
Source: "remote-read-only-fetch",
AsOf: asOf,
StaleAfterHours: staleAfterHours,
}, nil
}
func parseReviewQueueAsOf(value string) (time.Time, error) {
if strings.TrimSpace(value) == "" {
return time.Now().UTC(), nil
}
asOf, err := time.Parse(time.RFC3339, strings.TrimSpace(value))
if err != nil {
return time.Time{}, fmt.Errorf("invalid as-of %q: use RFC3339", value)
}
return asOf.UTC(), nil
}
func readReviewQueueInput(path string) (ReviewQueueInput, error) {
data, err := os.ReadFile(path)
if err != nil {
@ -234,12 +280,20 @@ func AnalyzeReviewQueue(input ReviewQueueInput, lang string) ReviewQueueResult {
if repository == "" {
repository = "local"
}
asOf := input.AsOf
if asOf.IsZero() {
asOf = time.Now().UTC()
}
staleAfterHours := input.StaleAfterHours
if staleAfterHours <= 0 {
staleAfterHours = 72
}
items := make([]ReviewQueueItem, 0, len(input.PullRequests))
focus := []string{}
for _, pr := range input.PullRequests {
summary := AnalyzePRSummary(pr, lang)
item := buildReviewQueueItem(pr, summary, lang)
item := buildReviewQueueItem(pr, summary, lang, asOf, staleAfterHours)
items = append(items, item)
focus = append(focus, item.ReviewFocus...)
}
@ -254,11 +308,13 @@ func AnalyzeReviewQueue(input ReviewQueueInput, lang string) ReviewQueueResult {
})
result := ReviewQueueResult{
Repository: repository,
TotalPRs: len(items),
Items: items,
TopFocus: limitStringsForReviewQueue(uniqueStrings(focus), 10),
Source: source,
Repository: repository,
TotalPRs: len(items),
Items: items,
TopFocus: limitStringsForReviewQueue(uniqueStrings(focus), 10),
Source: source,
AsOf: asOf,
StaleAfterHours: staleAfterHours,
}
for i := range result.Items {
result.Items[i].Rank = i + 1
@ -366,8 +422,15 @@ func sortReviewQueueDeltaItems(items []ReviewQueueDeltaItem, previousOnly bool)
})
}
func buildReviewQueueItem(pr PRSummaryInput, summary PRSummaryResult, lang string) ReviewQueueItem {
score, reasons := scoreReviewQueueItem(pr, summary)
func buildReviewQueueItem(pr PRSummaryInput, summary PRSummaryResult, lang string, asOf time.Time, staleAfterHours int) ReviewQueueItem {
updatedAt := pr.UpdatedAt
if updatedAt.IsZero() {
updatedAt = pr.CreatedAt
}
ageHours := elapsedHours(asOf, pr.CreatedAt)
waitingHours := elapsedHours(asOf, updatedAt)
stale := waitingHours >= staleAfterHours && !updatedAt.IsZero()
score, reasons := scoreReviewQueueItem(pr, summary, waitingHours, staleAfterHours)
priority := "low"
if score >= 70 {
priority = "high"
@ -390,10 +453,19 @@ func buildReviewQueueItem(pr PRSummaryInput, summary PRSummaryResult, lang strin
Reasons: reasons,
SuggestedAction: reviewQueueSuggestedAction(priority, summary.RiskLevel, summary.ChangeType, lang),
ReviewFocus: summary.ReviewFocus,
CreatedAt: pr.CreatedAt,
UpdatedAt: updatedAt,
AgeHours: ageHours,
WaitingHours: waitingHours,
Stale: stale,
ReviewState: normalizeReviewQueueState(pr.ReviewState),
Reviewers: append([]string(nil), pr.Reviewers...),
ReviewerCount: len(pr.Reviewers),
WaitingOn: reviewQueueWaitingOn(pr.ReviewState),
}
}
func scoreReviewQueueItem(pr PRSummaryInput, summary PRSummaryResult) (int, []string) {
func scoreReviewQueueItem(pr PRSummaryInput, summary PRSummaryResult, waitingHours, staleAfterHours int) (int, []string) {
score := 0
reasons := []string{}
switch summary.RiskLevel {
@ -443,12 +515,42 @@ func scoreReviewQueueItem(pr PRSummaryInput, summary PRSummaryResult) (int, []st
score += 8
reasons = append(reasons, "test signal not obvious")
}
if staleAfterHours > 0 && waitingHours >= staleAfterHours {
score += 12
reasons = append(reasons, fmt.Sprintf("no update for %dh", waitingHours))
} else if staleAfterHours > 0 && waitingHours >= staleAfterHours/2 {
score += 5
reasons = append(reasons, fmt.Sprintf("waiting %dh", waitingHours))
}
if score > 100 {
score = 100
}
return score, uniqueStrings(reasons)
}
func elapsedHours(asOf, eventAt time.Time) int {
if eventAt.IsZero() || asOf.Before(eventAt) {
return 0
}
return int(asOf.Sub(eventAt) / time.Hour)
}
func normalizeReviewQueueState(value string) string {
return strings.ToLower(strings.NewReplacer("-", "_", " ", "_").Replace(strings.TrimSpace(value)))
}
func reviewQueueWaitingOn(state string) string {
switch normalizeReviewQueueState(state) {
case "changes_requested", "changes_request", "request_changes":
return "author"
case "approved", "approve":
return "maintainer"
case "requested", "review_requested", "pending", "unreviewed", "reviewing":
return "reviewer"
}
return ""
}
func hasReviewQueueTestSignal(pr PRSummaryInput) bool {
for _, file := range pr.ChangedFiles {
if isTestPath(normalizedPath(file.Filename)) {
@ -617,6 +719,11 @@ func writeReviewQueueMarkdown(buf *bytes.Buffer, result ReviewQueueResult, lang
if _, err := fmt.Fprintf(buf, " - Action: %s\n", item.SuggestedAction); err != nil {
return err
}
if item.WaitingHours > 0 || item.AgeHours > 0 || item.WaitingOn != "" {
if _, err := fmt.Fprintf(buf, " - SLA: age `%dh`, waiting `%dh`, stale `%t`, waiting on `%s`, reviewers `%d`\n", item.AgeHours, item.WaitingHours, item.Stale, item.WaitingOn, item.ReviewerCount); err != nil {
return err
}
}
}
return nil
}

56
shortcuts/workflow/review_queue_test.go
View File

@ -7,6 +7,7 @@ import (
"path/filepath"
"strings"
"testing"
"time"
"github.com/gitlink-org/gitlink-cli/internal/client"
"github.com/gitlink-org/gitlink-cli/shortcuts/common"
@ -107,6 +108,40 @@ func TestCompareReviewQueueClassifiesChanges(t *testing.T) {
}
}
func TestAnalyzeReviewQueueIncludesSLAAndReviewOwnership(t *testing.T) {
asOf := time.Date(2026, 7, 20, 12, 0, 0, 0, time.UTC)
result := AnalyzeReviewQueue(ReviewQueueInput{
Repository: "owner/repo",
Source: "local-json",
AsOf: asOf,
StaleAfterHours: 72,
PullRequests: []PRSummaryInput{
{
Number: 42,
Title: "fix: update validation",
State: "open",
CreatedAt: asOf.Add(-120 * time.Hour),
UpdatedAt: asOf.Add(-80 * time.Hour),
ReviewState: "changes_requested",
Reviewers: []string{"alice", "bob"},
},
},
}, "en")
if len(result.Items) != 1 {
t.Fatalf("items = %d, want 1", len(result.Items))
}
item := result.Items[0]
if item.AgeHours != 120 || item.WaitingHours != 80 || !item.Stale {
t.Fatalf("freshness = age:%d waiting:%d stale:%t, want 120/80/true", item.AgeHours, item.WaitingHours, item.Stale)
}
if item.WaitingOn != "author" || item.ReviewerCount != 2 || item.ReviewState != "changes_requested" {
t.Fatalf("ownership = waiting_on:%q reviewers:%d state:%q", item.WaitingOn, item.ReviewerCount, item.ReviewState)
}
if !strings.Contains(strings.Join(item.Reasons, ","), "no update for 80h") {
t.Fatalf("reasons = %v, want stale reason", item.Reasons)
}
}
func TestReadReviewQueueResultRejectsInvalidJSON(t *testing.T) {
path := filepath.Join(t.TempDir(), "previous.json")
if err := os.WriteFile(path, []byte("not-json"), 0o600); err != nil {
@ -171,6 +206,10 @@ func TestFetchReviewQueuePullRequestsUsesReadOnlyQuery(t *testing.T) {
"description": "Adds queue analysis.",
"status": "open",
"creator": map[string]interface{}{"login": "alice"},
"created_at": "2026-07-18T12:00:00Z",
"updated_at": "2026-07-19T12:00:00Z",
"review_state": "requested",
"reviewers": []interface{}{map[string]interface{}{"login": "reviewer"}},
"additions": 130,
"deletions": 5,
},
@ -198,6 +237,9 @@ func TestFetchReviewQueuePullRequestsUsesReadOnlyQuery(t *testing.T) {
if prs[0].Number != 11 || prs[0].Repository != "owner/repo" || prs[0].State != "open" {
t.Fatalf("normalized PR = %+v, want owner/repo #11 open", prs[0])
}
if prs[0].ReviewState != "requested" || len(prs[0].Reviewers) != 1 || prs[0].Reviewers[0] != "reviewer" {
t.Fatalf("review metadata = state:%q reviewers:%v", prs[0].ReviewState, prs[0].Reviewers)
}
}
func TestRenderReviewQueueMarkdownAndTable(t *testing.T) {
@ -252,3 +294,17 @@ func TestRenderReviewQueueMarkdownIncludesChanges(t *testing.T) {
t.Fatalf("markdown = %q, want queue change summary", markdown)
}
}
func TestRenderReviewQueueMarkdownIncludesSLA(t *testing.T) {
result := ReviewQueueResult{
Repository: "owner/repo",
Items: []ReviewQueueItem{{Rank: 1, Number: 7, Title: "stale PR", WaitingHours: 80, AgeHours: 100, Stale: true, WaitingOn: "reviewer", ReviewerCount: 2}},
}
markdown, err := RenderReviewQueue(result, "markdown", "en")
if err != nil {
t.Fatalf("RenderReviewQueue returned error: %v", err)
}
if !strings.Contains(markdown, "SLA: age `100h`, waiting `80h`, stale `true`") {
t.Fatalf("markdown = %q, want SLA summary", markdown)
}
}