From 744e7ad8099e9640b6ada59a83110a1aa7d1e7c3 Mon Sep 17 00:00:00 2001 From: chenyunda218 Date: Thu, 10 Sep 2026 21:20:19 +0800 Subject: [PATCH] =?UTF-8?q?milestones=EF=BC=9A=E6=96=B0=E5=A2=9E=E8=B7=A8?= =?UTF-8?q?=E5=80=89=E5=BA=AB=E9=87=8C=E7=A8=8B=E7=A2=91=E7=B8=BD=E8=A6=BD?= =?UTF-8?q?=E5=91=BD=E4=BB=A4=EF=BC=88#31=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - teai milestones（不帶 --repo）輸出跨所屬組織各倉庫 open 里程碑概況， 對應 gitea.py milestones（管理者巡邏，agents AGENTS.md 10.1）： 欄位 repo/id/title/url/open_issues/closed_issues/due_on/due_hours/ overdue/unassigned/updated_at，排序期限近者在前、無期限最後。 - internal/workflow.MilestoneOverview：判定核心（Source 注入、離線可測）； MilestoneEntry 自訂 MarshalJSON，鍵集鍵序與 gitea.py 全等 （null 表示、due_hours 定點一位、unassigned PR 條目帶 author）。 - internal/workflow.APIClient 增 OpenMilestones／MilestoneOpenIssues （issues 端點刻意不帶 type=issues，PR 條目保留供覆蓋檢查，同 gitea.py）。 - milestones --repo a/b 維持現行單倉庫 list 語義不變。 - 空清單輸出 []（gitea.py 無輸出；#26 慣例差異，README 已文件化）。 - 交叉驗證：同帳號同時跑 gitea.py milestones 與 teai milestones， 含逾期／未到期／無期限里程碑與未分派 issue／PR 條目，輸出位元組全等。 --- README.md | 50 ++++- internal/cli/dailyops_commands.go | 35 ++- internal/cli/milestones_commands.go | 97 +++++++++ internal/cli/milestones_commands_test.go | 188 ++++++++++++++++ internal/workflow/giteaapi.go | 36 +++- internal/workflow/milestones.go | 256 ++++++++++++++++++++++ internal/workflow/milestones_test.go | 262 +++++++++++++++++++++++ 7 files changed, 916 insertions(+), 8 deletions(-) create mode 100644 internal/cli/milestones_commands.go create mode 100644 internal/cli/milestones_commands_test.go create mode 100644 internal/workflow/milestones.go create mode 100644 internal/workflow/milestones_test.go diff --git a/README.md b/README.md index 8e0d63a..d046430 100644 --- a/README.md +++ b/README.md @@ -86,6 +86,8 @@ teai pulls comment --repo / --body … --yes # labels／milestones／releases／repos teai labels list --repo / teai labels create --repo / --name … [--color #RRGGBB] [--description …] --yes +teai milestones # 跨倉庫 open 里程碑總覽（gitea.py milestones 對應；期限近者在前） +teai milestones --repo / # 同 milestones list（單倉庫，維持既有語義） teai milestones list --repo / [--state open|closed|all] teai milestones create --repo / --title … [--description …] [--due RFC3339] --yes teai releases list --repo / @@ -207,6 +209,47 @@ PR 改帶 `author` 與 `reviewers` 欄位。`reason` 取值： - issue：`no-assignee`、`assignee-idle`、`no-commenter`、`waiting-outside`、`parent-tracking` - PR：`no-reviewer`、`author-idle`、`reviewer-idle`、`no-commenter` +### `teai milestones` — 跨倉庫里程碑總覽 + +```sh +teai milestones # 各倉庫 open 里程碑概況（跨所屬組織；期限近者在前） +teai milestones --output table +``` + +管理者巡邏用（`gitea.py milestones` 對應，agents AGENTS.md 10.1）。帶 `--repo` 時 +維持現行單倉庫 `list` 語義（`teai milestones --repo a/b` ＝ `teai milestones list --repo a/b`）。 + +每筆欄位（鍵集鍵序與 `gitea.py` 全等，實測位元組一致）： + +```json +{ + "repo": "alterminal/test", + "id": 6, + "title": "xcheck31-ms-overdue", + "url": "https://gitea.alterminal.com/alterminal/test/milestone/6", + "open_issues": 2, + "closed_issues": 0, + "due_on": "2026-09-08T08:00:00+08:00", + "due_hours": 61.3, + "overdue": true, + "unassigned": [ + { + "type": "issue", + "number": 14, + "title": "…", + "url": "https://gitea.alterminal.com/alterminal/test/issues/14" + } + ], + "updated_at": "2026-09-10T21:17:37+08:00" +} +``` + +- **排序**：`due_on` 近者在前；無期限者最後（`gitea.py` 的 `(due_on is None, due_on)` 鍵）。 +- **`overdue`／`due_hours`**：期限已過為 `true`（`due_hours` 正數）；無期限 → `null`。 +- **`unassigned`**：該里程碑 open 條目（issue 與 PR）中無 assignee 者的摘要；PR 條目另帶 `author`。 +- **`updated_at`**：里程碑本身與其 open 條目 `updated_at` 的最大值（判斷活躍度用）。 +- 空輸出 → `[]`（`gitea.py` 無輸出；依 #26 慣例差異）。 + ### `teai members [--has-work]` ```sh @@ -266,6 +309,7 @@ teai whoami # 目前帳號（讀 tea 組態） | --- | --- | --- | | `next` | `teai next` | 相同：author-PR → reviewer-PR → issue，最久未更新優先 | | `stalled [--hours N]` | `teai stalled [--hours N]` | 相同，含 xref 父子追蹤與冷卻 | +| `milestones` | `teai milestones` | 相同：跨倉庫 open 里程碑總覽，期限近者在前（#31） | | `members [--has-work]` | `teai members [--has-work]` | 相同 | | `pulls`／`pulls --mine`／`pulls --reviewer` | `teai pulls [--mine\|--reviewer]` | 相同 | | `mine` | `teai mine` | 相同 | @@ -274,14 +318,14 @@ teai whoami # 目前帳號（讀 tea 組態） 已知輸出差異（刻意保留，機器可讀優先）： - **空清單**：`gitea.py` 的 `_dump` 對空清單**不輸出任何內容**；teai 的清單類命令 - （`mine`／`pulls`）空清單輸出 `[]`。對 JSON 消費者來說 `[]` 比「無輸出」更明確， + （`mine`／`pulls`／`milestones` 總覽）空清單輸出 `[]`。對 JSON 消費者來說 `[]` 比「無輸出」更明確， 交叉驗證時以此差異為準。`next` 兩者語義相同（無工作 → `null`／「沒有未完成的工作」）。 - **清單欄位集（`mine`／`pulls`）**：`gitea.py` 直接傾倒完整 Gitea API 物件 （`_dump` 的副作用，欄位集隨 Gitea 版本浮動）；teai 輸出策展摘要欄位 （`mine`：repo／number／title／url；`pulls`：number／title／state／author／ head／base／updated_at…依命令定義）。交叉驗證比對**項目集合**（列出哪些 - issue／PR）與判定語義，不逐欄位比對；`next`／`stalled` 兩者為策展欄位且 - 鍵集鍵序全等，可逐欄位比對。判定 #26（維持摘要、文件化差異）。 + issue／PR）與判定語義，不逐欄位比對；`next`／`stalled`／`milestones` 總覽 + 兩者為策展欄位且鍵集鍵序全等，可逐欄位比對（#31 實測位元組一致）。判定 #26（維持摘要、文件化差異）。 - **全域選項位置**：teai 的全域選項（`--output` 等）可出現在命令之前或之後， 且可與命令旗標交錯（`teai members --has-work --output table`）； gitea.py 的旗標剖析較寬鬆，兩者命令列介面以此行為對齊。 diff --git a/internal/cli/dailyops_commands.go b/internal/cli/dailyops_commands.go index 58e6dab..4155a40 100644 --- a/internal/cli/dailyops_commands.go +++ b/internal/cli/dailyops_commands.go @@ -26,7 +26,7 @@ func init() { register(&command{name: "issues", usage: "issues 管理（list/view/create/close/comment）", run: runIssues}) register(&command{name: "pulls", usage: "PR 管理（list/view/create/merge/comment；無子命令＝工作流清單）", run: runPullsDaily}) register(&command{name: "labels", usage: "標籤管理（list/create）", run: runLabels}) - register(&command{name: "milestones", usage: "里程碑管理（list/create）", run: runMilestones}) + register(&command{name: "milestones", usage: "里程碑（跨倉庫總覽；list/create 管理單倉庫）", run: runMilestones}) register(&command{name: "releases", usage: "發佈清單（list）", run: runReleases}) register(&command{name: "repos", usage: "倉庫查詢（list）", run: runRepos}) register(&command{name: "api", usage: "任意 API 呼叫（--method/--data；寫入動詞需 --yes）", run: runAPIDirect}) @@ -650,10 +650,12 @@ func runLabelsCreate(env *Env, args []string) error { // ---- milestones ---- -// runMilestones：teai milestones list｜create … +// runMilestones：teai milestones [list|create] …；不帶子命令時輸出 +// 跨倉庫里程碑總覽（#31，對應 gitea.py milestones）。帶 --repo 直接 +// 跟在 milestones 之後時維持現行單倉庫 list 語義。 func runMilestones(env *Env, args []string) error { if len(args) == 0 { - return &ErrUsage{Msg: "milestones 需要子命令：list | create"} + return runMilestonesOverview(env) } sub, rest := args[0], args[1:] switch sub { @@ -662,7 +664,32 @@ func runMilestones(env *Env, args []string) error { case "create": return runMilestonesCreate(env, rest) default: - return &ErrUsage{Msg: fmt.Sprintf("milestones 未知子命令 %q（可用：list | create）", sub)} + if !strings.HasPrefix(sub, "-") { + return &ErrUsage{Msg: fmt.Sprintf("milestones 未知子命令 %q（可用：list | create；或不帶參數輸出跨倉庫總覽）", sub)} + } + // milestones 之後直接跟旗標（非子命令）：帶 --repo → 整串轉發， + // 維持現行單倉庫 list 語義（--state 等旗標一併生效）；否則為 + // 跨倉庫總覽（總覽不接受任何命令旗標，空 FlagSet 讓未知旗標 + // 報用法錯誤）。 + hasRepo := false + for _, a := range args { + if a == "--repo" || strings.HasPrefix(a, "--repo=") { + hasRepo = true + break + } + } + if hasRepo { + return runMilestonesList(env, args) + } + fs := flag.NewFlagSet("teai milestones", flag.ContinueOnError) + fs.SetOutput(env.Err) + if err := parseFlags(fs, args); err != nil { + return err + } + if fs.NArg() != 0 { + return &ErrUsage{Msg: "milestones 不接受位置參數（子命令：list | create）"} + } + return runMilestonesOverview(env) } } diff --git a/internal/cli/milestones_commands.go b/internal/cli/milestones_commands.go new file mode 100644 index 0000000..50fcd03 --- /dev/null +++ b/internal/cli/milestones_commands.go @@ -0,0 +1,97 @@ +// milestones_commands.go — 跨倉庫里程碑總覽命令的 CLI 接線（#31）： +// teai milestones（不帶 --repo）。 +// +// 核心邏輯在 internal/workflow（MilestoneOverview），本檔只做旗標 +// 剖析、資料源接線與輸出格式化（與 stalled_commands.go 同模式）。 +// 輸出與 gitea.py milestones 位元組相容（MilestoneEntry 自訂 +// MarshalJSON；縮排 2、停用 HTML 轉義、空清單輸出 []，見 #26 慣例）。 +package cli + +import ( + "fmt" + "time" + + "gitea.alterminal.com/alterminal/teai/internal/gitea" + "gitea.alterminal.com/alterminal/teai/internal/workflow" +) + +// newMilestoneSourceFunc 建立總覽的資料源；宣告為變數讓接線層測試 +// 可注入假資料源（與 newStalledSourceFunc 同模式）。 +var newMilestoneSourceFunc = newMilestoneSource + +// newMilestoneSource 依全域選項建立 workflow.MilestoneSource（API 實作）。 +func newMilestoneSource(env *Env) (workflow.MilestoneSource, error) { + token, _, err := gitea.ResolveToken(gitea.AuthOptions{ + FlagToken: env.Globals.Token, + SiteURL: env.Globals.URL, + ConfigPath: env.Globals.ConfigPath, + }) + if err != nil { + return nil, err + } + client, err := gitea.New(env.Globals.URL, token, env.Globals.Timeout) + if err != nil { + return nil, err + } + return &workflow.APIClient{Client: client}, nil +} + +// milestonesNowFunc 回傳總覽的基準時刻；宣告為變數讓測試可固定時刻。 +var milestonesNowFunc = time.Now + +// milestoneEntryRow 把 MilestoneEntry 轉成 table 列（unassigned 僅 JSON +// 模式輸出完整摘要；table 給人工抽查用，取計數）。 +func milestoneEntryRow(e workflow.MilestoneEntry) gitea.Values { + dueOn := "" + if e.DueOn != nil { + dueOn = *e.DueOn + } + dueHours := "" + if e.DueHours != nil { + dueHours = fmt.Sprintf("%.1f", *e.DueHours) + } + updatedAt := "" + if e.UpdatedAt != nil { + updatedAt = *e.UpdatedAt + } + id := "" + if e.ID != nil { + id = fmt.Sprintf("%d", *e.ID) + } + return gitea.Values{ + e.Repo, id, e.Title, e.URL, + e.OpenIssues, e.ClosedIssues, dueOn, dueHours, + e.Overdue, len(e.Unassigned), updatedAt, + } +} + +// runMilestonesOverview：teai milestones（跨倉庫總覽）。 +// JSON 輸出與 gitea.py milestones 位元組相容；空清單輸出 []（#26 慣例： +// gitea.py 對空清單不輸出，teai 輸出 [] 供 JSON 消費者明確判斷）。 +func runMilestonesOverview(env *Env) error { + src, err := newMilestoneSourceFunc(env) + if err != nil { + return err + } + entries, err := workflow.MilestoneOverview(src, env.Globals.URL, milestonesNowFunc()) + if err != nil { + return err + } + p := printer(env) + if p.Format == gitea.FormatTable { + rows := make([]gitea.Values, 0, len(entries)) + for i := range entries { + rows = append(rows, milestoneEntryRow(entries[i])) + } + return p.PrintList([]gitea.Field{ + {Name: "repo"}, {Name: "id"}, {Name: "title"}, {Name: "url"}, + {Name: "open_issues"}, {Name: "closed_issues"}, {Name: "due_on"}, + {Name: "due_hours"}, {Name: "overdue"}, {Name: "unassigned"}, {Name: "updated_at"}, + }, rows) + } + if len(entries) == 0 { + _, err := fmt.Fprintln(env.Out, "[]") + return err + } + return printJSON(env.Out, entries) +} diff --git a/internal/cli/milestones_commands_test.go b/internal/cli/milestones_commands_test.go new file mode 100644 index 0000000..3b40e18 --- /dev/null +++ b/internal/cli/milestones_commands_test.go @@ -0,0 +1,188 @@ +// milestones_commands_test.go — 跨倉庫里程碑總覽的 CLI 接線層測試（#31）： +// 注入假 MilestoneSource，驗證 Run→dispatch→輸出完整路徑，不走網路 +// （與 stalled_commands_test.go 同模式）。 +package cli + +import ( + "encoding/json" + "net/http" + "net/http/httptest" + "strings" + "testing" + "time" + + "gitea.alterminal.com/alterminal/teai/internal/workflow" +) + +// stubMilestoneSource 以記憶體資料實作 workflow.MilestoneSource。 +type stubMilestoneSource struct { + orgs []string + repos map[string][]workflow.Repo + milestones map[string][]workflow.Milestone + openIssues map[string][]workflow.Issue // key: owner/repo?milestone= +} + +func (s *stubMilestoneSource) MyOrganizations() ([]string, error) { return s.orgs, nil } +func (s *stubMilestoneSource) OrganizationRepositories(org string) ([]workflow.Repo, error) { + return s.repos[org], nil +} +func (s *stubMilestoneSource) OpenMilestones(owner, repo string) ([]workflow.Milestone, error) { + return s.milestones[owner+"/"+repo], nil +} +func (s *stubMilestoneSource) MilestoneOpenIssues(owner, repo, title string) ([]workflow.Issue, error) { + return s.openIssues[owner+"/"+repo+"?milestone="+title], nil +} + +// newStubMilestoneEnv 注入假資料源並固定時刻。 +func newStubMilestoneEnv(t *testing.T, src *stubMilestoneSource, frozen time.Time) { + t.Helper() + origSrc, origNow := newMilestoneSourceFunc, milestonesNowFunc + newMilestoneSourceFunc = func(env *Env) (workflow.MilestoneSource, error) { return src, nil } + milestonesNowFunc = func() time.Time { return frozen } + t.Cleanup(func() { + newMilestoneSourceFunc, milestonesNowFunc = origSrc, origNow + }) +} + +// stubPullIssue 以 JSON 建構帶 pull_request 標記的條目（pullMarker 未匯出， +// 測試從套件外以 API 回應的形狀建構，走 Issue.UnmarshalJSON 同一路徑）。 +func stubPullIssue(t *testing.T) workflow.Issue { + t.Helper() + var issue workflow.Issue + err := json.Unmarshal([]byte(`{ + "number": 32, "title": "文件", "state": "open", + "updated_at": "2026-09-08T00:00:00Z", + "html_url": "https://gitea.alterminal.com/alterminal/agents/pulls/32", + "user": {"username": "alex"}, + "pull_request": {} + }`), &issue) + if err != nil { + t.Fatalf("建構 stub PR 條目失敗：%v", err) + } + return issue +} + +// idPtr／msPtr 是測試用指標 helper（workflow 套件內同名函式未匯出）。 +func idPtr(i int64) *int64 { return &i } +func msPtr(s string) *string { return &s } + +// newStubMilestoneData 建構總覽情境：兩倉庫各一里程碑、一個未分派 PR。 +func newStubMilestoneData(t *testing.T) *stubMilestoneSource { + due := "2026-09-09T00:00:00Z" + return &stubMilestoneSource{ + orgs: []string{"alterminal"}, + repos: map[string][]workflow.Repo{"alterminal": { + {Name: "agents"}, {Name: "teai"}, + }}, + milestones: map[string][]workflow.Milestone{ + "alterminal/agents": { + {ID: idPtr(7), Title: "MVP", State: "open", + DueOn: &due, UpdatedAt: "2026-09-01T00:00:00Z", + OpenIssues: 1, ClosedIssues: 0}, + }, + "alterminal/teai": { + {ID: idPtr(3), Title: "CLI", State: "open", + DueOn: msPtr("2026-09-12T00:00:00Z"), UpdatedAt: "2026-09-05T00:00:00Z", + OpenIssues: 1, ClosedIssues: 2}, + }, + }, + openIssues: map[string][]workflow.Issue{ + "alterminal/agents?milestone=MVP": {stubPullIssue(t)}, + }, + } +} + +// TestWiringMilestonesOverview 驗證 teai milestones 輸出跨倉庫總覽 +// （JSON 縮排 2、鍵序與欄位齊 gitea.py）。 +func TestWiringMilestonesOverview(t *testing.T) { + newStubMilestoneEnv(t, newStubMilestoneData(t), time.Date(2026, 9, 10, 8, 0, 0, 0, time.UTC)) + stdout, _, code := run("milestones") + if code != 0 { + t.Fatalf("milestones 應回 0，得到 %d（stdout=%q）", code, stdout) + } + for _, want := range []string{ + `"repo": "alterminal/agents"`, + `"title": "MVP"`, + `"overdue": true`, + `"type": "pull"`, + `"author": "alex"`, + } { + if !strings.Contains(stdout, want) { + t.Fatalf("milestones 輸出應含 %q，得到：\n%s", want, stdout) + } + } + // 排序：agents MVP（09-09）在 teai CLI（09-12）前。 + if strings.Index(stdout, `"title": "MVP"`) > strings.Index(stdout, `"title": "CLI"`) { + t.Fatalf("期限近者應在前：\n%s", stdout) + } +} + +// TestWiringMilestonesEmpty 驗證無里程碑 → []（#26 慣例）。 +func TestWiringMilestonesEmpty(t *testing.T) { + newStubMilestoneEnv(t, &stubMilestoneSource{ + orgs: []string{"alterminal"}, + repos: map[string][]workflow.Repo{"alterminal": {{Name: "agents"}}}, + milestones: map[string][]workflow.Milestone{}, + openIssues: map[string][]workflow.Issue{}, + }, time.Date(2026, 9, 10, 8, 0, 0, 0, time.UTC)) + stdout, _, code := run("milestones") + if code != 0 { + t.Fatalf("milestones 空清單應回 0，得到 %d", code) + } + if strings.TrimSpace(stdout) != "[]" { + t.Fatalf("無里程碑應輸出 []，得到 %q", stdout) + } +} + +// TestWiringMilestonesTable 驗證 table 輸出（人工抽查用）。 +func TestWiringMilestonesTable(t *testing.T) { + newStubMilestoneEnv(t, newStubMilestoneData(t), time.Date(2026, 9, 10, 8, 0, 0, 0, time.UTC)) + stdout, _, code := run("milestones", "--output", "table") + if code != 0 { + t.Fatalf("milestones --output table 應回 0，得到 %d", code) + } + for _, want := range []string{"repo", "overdue", "MVP", "alterminal/agents"} { + if !strings.Contains(stdout, want) { + t.Fatalf("table 輸出應含 %q，得到：\n%s", want, stdout) + } + } +} + +// TestWiringMilestonesRepoFlagCompat 驗證 teai milestones --repo a/b +// 維持現行單倉庫 list 語義（#31：帶 --repo 時不變）。 +func TestWiringMilestonesRepoFlagCompat(t *testing.T) { + var gotPath, gotQuery string + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + gotPath, gotQuery = r.URL.Path, r.URL.RawQuery + w.Write([]byte(`[{"title":"v1","state":"open","description":"","due_on":""}]`)) + })) + t.Cleanup(srv.Close) + stdout, _, code := run("--url", srv.URL, "milestones", "--repo", "a/b") + if code != 0 { + t.Fatalf("milestones --repo a/b 應回 0，得到 %d", code) + } + if gotPath != "/api/v1/repos/a/b/milestones" { + t.Fatalf("應呼叫 /repos/a/b/milestones，得到 %s", gotPath) + } + if !strings.Contains(gotQuery, "state=open") { + t.Fatalf("查詢應含 state=open，得到 %q", gotQuery) + } + if !strings.Contains(stdout, `"title":"v1"`) { + t.Fatalf("輸出應含 title v1，得到：%s", stdout) + } +} + +// TestWiringMilestonesUsage 驗證未知子命令與位置參數 → exit 2。 +func TestWiringMilestonesUsage(t *testing.T) { + newStubMilestoneEnv(t, newStubMilestoneData(t), time.Date(2026, 9, 10, 8, 0, 0, 0, time.UTC)) + if _, _, code := run("milestones", "bogus"); code != int(ExitUsage) { + t.Fatalf("milestones bogus 應回 ExitUsage，得到 %d", code) + } + if _, _, code := run("milestones", "extra", "arg"); code != int(ExitUsage) { + t.Fatalf("milestones 位置參數應回 ExitUsage，得到 %d", code) + } + // milestones list 仍照舊要求 --repo。 + if _, _, code := run("milestones", "list"); code != int(ExitUsage) { + t.Fatalf("milestones list 缺 --repo 應回 ExitUsage，得到 %d", code) + } +} diff --git a/internal/workflow/giteaapi.go b/internal/workflow/giteaapi.go index 1d187d5..a7c2f64 100644 --- a/internal/workflow/giteaapi.go +++ b/internal/workflow/giteaapi.go @@ -173,5 +173,39 @@ func (a *APIClient) IssueComments(owner, repo string, number int64) ([]Comment, return a.ListComments(owner, repo, number) } -// 編譯期確認 APIClient 同時實作 Client 與 StalledSource。 +// ── MilestoneSource 面向（#31 跨倉庫里程碑總覽）──────────────────────── +// APIClient 在 StalledSource 之外另實作 MilestoneSource，讓 milestones +// 總覽命令與既有命令共用同一個 HTTP 用戶端；查詢參數對照 gitea.py 的 +// list_open_milestones_for_repository／_milestone_open_issues。 + +// OpenMilestones 回傳倉庫的 open 里程碑（GET /repos/{o}/{r}/milestones?state=open）。 +func (a *APIClient) OpenMilestones(owner, repo string) ([]Milestone, error) { + var ms []Milestone + path := "/repos/" + url.PathEscape(owner) + "/" + url.PathEscape(repo) + "/milestones" + opts := gitea.ListOptions{Extra: url.Values{"state": {"open"}}} + if err := a.Client.ListAll(context.Background(), path, opts, &ms); err != nil { + return nil, err + } + return ms, nil +} + +// MilestoneOpenIssues 回傳掛在指定里程碑（依名稱過濾，Gitea 以 +// milestones=<title> 查詢）的 open 條目。刻意**不**帶 type=issues—— +// PR 亦屬里程碑條目，保留兩者供覆蓋檢查（同 gitea.py +// _milestone_open_issues；PR 帶 pull_request 標記由 workflow 判別）。 +func (a *APIClient) MilestoneOpenIssues(owner, repo, milestoneTitle string) ([]Issue, error) { + var issues []Issue + path := "/repos/" + url.PathEscape(owner) + "/" + url.PathEscape(repo) + "/issues" + opts := gitea.ListOptions{Extra: url.Values{ + "state": {"open"}, + "milestones": {milestoneTitle}, + }} + if err := a.Client.ListAll(context.Background(), path, opts, &issues); err != nil { + return nil, err + } + return issues, nil +} + +// 編譯期確認 APIClient 同時實作 Client、StalledSource 與 MilestoneSource。 var _ StalledSource = (*APIClient)(nil) +var _ MilestoneSource = (*APIClient)(nil) diff --git a/internal/workflow/milestones.go b/internal/workflow/milestones.go new file mode 100644 index 0000000..1c9103c --- /dev/null +++ b/internal/workflow/milestones.go @@ -0,0 +1,256 @@ +// milestones.go — 跨倉庫里程碑總覽（teai #31；gitea.py milestones 的對應實作）。 +// +// 各倉庫 open milestone 概況（管理者巡邏用，agents AGENTS.md 10.1）：期限近者 +// 在前的排序、逾期判定、未分派條目摘要與活躍度（updated_at 取里程碑本身與 +// 其 open 條位的最大值）。判定與輸出規則以 AGENTS.md 為單一來源，行為基準是 +// gitea.py 的 list_milestone_overview，本檔只實作、不改義。 +package workflow + +import ( + "fmt" + "sort" + "strconv" + "strings" + "time" +) + +// Milestone 是里程碑物件（僅取總覽會用到的欄位）。 +// ID 與 DueOn 用指標：Gitea 回 null／缺漏時輸出 null +// （對應 gitea.py milestone.get("id")／get("due_on") 的 None 語義）。 +type Milestone struct { + ID *int64 `json:"id"` + Title string `json:"title"` + State string `json:"state"` + DueOn *string `json:"due_on"` + UpdatedAt string `json:"updated_at"` + OpenIssues int64 `json:"open_issues"` + ClosedIssues int64 `json:"closed_issues"` +} + +// MilestoneSource 是跨倉庫里程碑總覽需要的資料源（CLI 層以 API 實作； +// 測試注入假資料，與 Source／StalledSource 同模式）。 +type MilestoneSource interface { + // MyOrganizations 回傳目前帳號所屬組織清單。 + MyOrganizations() ([]string, error) + // OrganizationRepositories 回傳組織的倉庫清單。 + OrganizationRepositories(org string) ([]Repo, error) + // OpenMilestones 回傳倉庫的 open 里程碑。 + OpenMilestones(owner, repo string) ([]Milestone, error) + // MilestoneOpenIssues 回傳掛在指定里程碑（依名稱過濾）的 open + // issue 與 PR。刻意不設 type 過濾——兩者都保留供覆蓋檢查 + //（同 gitea.py _milestone_open_issues 的查詢參數；PR 帶 + // pull_request 標記，由本套件判別）。 + MilestoneOpenIssues(owner, repo, milestoneTitle string) ([]Issue, error) +} + +// UnassignedEntry 是里程碑 open 條目中未分派者的摘要。 +type UnassignedEntry struct { + Type string + Number int64 + Title string + URL string + // Author 僅 pull 條目輸出（且作者已知時；對應 gitea.py 只在 + // _pr_author_username 非空時放 author 鍵）。 + Author string +} + +// MarshalJSON 輸出鍵集與鍵序與 gitea.py 一致的物件。 +func (u UnassignedEntry) MarshalJSON() ([]byte, error) { + var b strings.Builder + b.WriteString(`{"type":`) + writeJSON(&b, u.Type) + b.WriteString(`,"number":`) + fmt.Fprintf(&b, "%d", u.Number) + b.WriteString(`,"title":`) + writeJSON(&b, u.Title) + b.WriteString(`,"url":`) + writeJSON(&b, u.URL) + if u.Author != "" { + b.WriteString(`,"author":`) + writeJSON(&b, u.Author) + } + b.WriteString(`}`) + return []byte(b.String()), nil +} + +// MilestoneEntry 是總覽的單筆輸出（欄位對應 gitea.py list_milestone_overview +// 的 dict 鍵序：repo、id、title、url、open_issues、closed_issues、due_on、 +// due_hours、overdue、unassigned、updated_at）。 +type MilestoneEntry struct { + Repo string + ID *int64 + Title string + URL string + OpenIssues int64 + ClosedIssues int64 + DueOn *string + DueHours *float64 + Overdue bool + Unassigned []UnassignedEntry + UpdatedAt *string +} + +// MarshalJSON 輸出鍵集與鍵序與 gitea.py 完全一致的物件 +// （與 Item／stalled 的做法相同：手寫鍵序，null／浮點格式對齊 Python）。 +func (e MilestoneEntry) MarshalJSON() ([]byte, error) { + var b strings.Builder + b.WriteString(`{"repo":`) + writeJSON(&b, e.Repo) + b.WriteString(`,"id":`) + if e.ID != nil { + fmt.Fprintf(&b, "%d", *e.ID) + } else { + b.WriteString("null") + } + b.WriteString(`,"title":`) + writeJSON(&b, e.Title) + b.WriteString(`,"url":`) + writeJSON(&b, e.URL) + b.WriteString(`,"open_issues":`) + fmt.Fprintf(&b, "%d", e.OpenIssues) + b.WriteString(`,"closed_issues":`) + fmt.Fprintf(&b, "%d", e.ClosedIssues) + b.WriteString(`,"due_on":`) + writeJSON(&b, e.DueOn) + b.WriteString(`,"due_hours":`) + if e.DueHours != nil { + // Python round(x, 1) 的 json 輸出是 48.0／10.4（定點一位小數）。 + b.WriteString(strconv.FormatFloat(round1(*e.DueHours), 'f', 1, 64)) + } else { + b.WriteString("null") + } + b.WriteString(`,"overdue":`) + b.WriteString(strconv.FormatBool(e.Overdue)) + b.WriteString(`,"unassigned":`) + writeJSON(&b, e.Unassigned) + b.WriteString(`,"updated_at":`) + writeJSON(&b, e.UpdatedAt) + b.WriteString(`}`) + return []byte(b.String()), nil +} + +// MilestoneOverview 收集跨組織各倉庫的 open 里程碑概況，依（due_on， +// 無則視為最遠）由近到遠排序（穩定排序：同 due_on 者保持掃描順序， +// 對應 Python list.sort 的穩定性）。webBase 是站點網址前綴 +// （scheme://host），空字串時 url 欄位輸出 ""（同 gitea.py 在 +// GITEA_WEB_DOMAIN 缺漏時的行為）。 +func MilestoneOverview(src MilestoneSource, webBase string, now time.Time) ([]MilestoneEntry, error) { + orgs, err := src.MyOrganizations() + if err != nil { + return nil, err + } + out := []MilestoneEntry{} + for _, org := range orgs { + repos, err := src.OrganizationRepositories(org) + if err != nil { + return nil, err + } + for _, repo := range repos { + if repo.Name == "" || repo.Empty { + continue + } + ms, err := src.OpenMilestones(org, repo.Name) + if err != nil { + return nil, err + } + for i := range ms { + entry, err := milestoneEntry(src, org, repo.Name, &ms[i], webBase, now) + if err != nil { + return nil, err + } + out = append(out, entry) + } + } + } + // gitea.py 的排序鍵：(due_on is None, due_on or "")——有期限者在前、 + // 期限近者在前；無期限者在後。 + sort.SliceStable(out, func(a, bb int) bool { + x, y := out[a].DueOn, out[bb].DueOn + if (x == nil) != (y == nil) { + return y == nil + } + if x != nil { + return *x < *y + } + return false + }) + return out, nil +} + +// milestoneEntry 計算單一里程碑的總覽欄位（對應 gitea.py 迴圈體）。 +func milestoneEntry(src MilestoneSource, org, repo string, m *Milestone, webBase string, now time.Time) (MilestoneEntry, error) { + // due_hours／overdue：due_on 缺漏或無法解析 → null／false。 + // Python 以未捨入值判定 overdue（round 只作用於輸出）， + // 邊界（如 0.04 小時 → overdue=true、due_hours=0.0）保持一致。 + var dueHours *float64 + overdue := false + if m.DueOn != nil { + if due, ok := parseMoment(*m.DueOn); ok { + raw := now.Sub(due).Hours() + dueHours = &raw + overdue = raw > 0 + } + } + openEntries, err := src.MilestoneOpenIssues(org, repo, m.Title) + if err != nil { + return MilestoneEntry{}, err + } + // 未分派條目摘要（assignees 為空者）；updated_at 取里程碑本身與 + // 各 open 條目 updated_at 的最大值（供巡邏判斷活躍度）。 + unassigned := []UnassignedEntry{} + moments := []time.Time{} + if updated, ok := parseMoment(m.UpdatedAt); ok { + moments = append(moments, updated) + } + for i := range openEntries { + entry := &openEntries[i] + if updated, ok := parseMoment(entry.UpdatedAt); ok { + moments = append(moments, updated) + } + if len(AssigneeNames(entry)) > 0 { + continue + } + summary := UnassignedEntry{ + Type: "issue", + Number: entry.issueNumber(), + Title: entry.Title, + URL: entry.WebURL(), + } + if entry.PullRequest != nil { + summary.Type = "pull" + if author := entry.User.Name(); author != "" { + summary.Author = author + } + } + unassigned = append(unassigned, summary) + } + var updatedAt *string + if len(moments) > 0 { + s := FormatMoment(maxTime(moments)) + updatedAt = &s + } + return MilestoneEntry{ + Repo: org + "/" + repo, + ID: m.ID, + Title: m.Title, + URL: milestoneURL(webBase, org, repo, m.ID), + OpenIssues: m.OpenIssues, + ClosedIssues: m.ClosedIssues, + DueOn: m.DueOn, + DueHours: dueHours, + Overdue: overdue, + Unassigned: unassigned, + UpdatedAt: updatedAt, + }, nil +} + +// milestoneURL 組里程碑網頁網址；webBase 空或 id 缺漏回 "" +// （對應 gitea.py _milestone_url 的兩個空值條件。Python 原版不做 +// URL 跳脫——一般組織／倉庫名皆為安全字元，這裡保持一致以求位元組相容）。 +func milestoneURL(webBase, org, repo string, id *int64) string { + if webBase == "" || id == nil { + return "" + } + return strings.TrimRight(webBase, "/") + "/" + org + "/" + repo + + "/milestone/" + strconv.FormatInt(*id, 10) +} diff --git a/internal/workflow/milestones_test.go b/internal/workflow/milestones_test.go new file mode 100644 index 0000000..f8e3e14 --- /dev/null +++ b/internal/workflow/milestones_test.go @@ -0,0 +1,262 @@ +// milestones_test.go — MilestoneOverview 的單元測試（#31）。 +// +// 資料源注入假實作（離線可測）；鍵序、null 表示、排序與 overdue +// 判定對照 gitea.py list_milestone_overview 的 Python 語義。 +package workflow + +import ( + "encoding/json" + "strings" + "testing" + "time" +) + +// fakeMilestoneSource 以記憶體資料實作 MilestoneSource。 +type fakeMilestoneSource struct { + orgs []string + repos map[string][]Repo + milestones map[string][]Milestone + openIssues map[string][]Issue // key: owner/repo?milestone=<title> +} + +func (f *fakeMilestoneSource) MyOrganizations() ([]string, error) { return f.orgs, nil } +func (f *fakeMilestoneSource) OrganizationRepositories(org string) ([]Repo, error) { + return f.repos[org], nil +} +func (f *fakeMilestoneSource) OpenMilestones(owner, repo string) ([]Milestone, error) { + return f.milestones[owner+"/"+repo], nil +} +func (f *fakeMilestoneSource) MilestoneOpenIssues(owner, repo, title string) ([]Issue, error) { + return f.openIssues[owner+"/"+repo+"?milestone="+title], nil +} + +func msPtr(s string) *string { return &s } +func idPtr(i int64) *int64 { return &i } + +// newMilestoneFixture 建構情境：alterminal 兩倉庫、三里程碑 +// （teai 有期限將至、agents 有逾期與無期限）。 +func newMilestoneFixture() *fakeMilestoneSource { + return &fakeMilestoneSource{ + orgs: []string{"alterminal"}, + repos: map[string][]Repo{"alterminal": { + {Name: "agents", HasPullRequests: boolPtr(true)}, + {Name: "teai", HasPullRequests: boolPtr(true)}, + {Name: "empty-repo", Empty: true}, // 空倉庫應跳過 + }}, + milestones: map[string][]Milestone{ + "alterminal/agents": { + {ID: idPtr(7), Title: "MVP", State: "open", + DueOn: msPtr("2026-09-09T00:00:00Z"), UpdatedAt: "2026-09-01T00:00:00Z", + OpenIssues: 3, ClosedIssues: 1}, + {ID: idPtr(8), Title: "v1", State: "open", + DueOn: nil, UpdatedAt: "2026-09-02T00:00:00Z", + OpenIssues: 1, ClosedIssues: 0}, + }, + "alterminal/teai": { + {ID: idPtr(3), Title: "CLI", State: "open", + DueOn: msPtr("2026-09-12T00:00:00Z"), UpdatedAt: "2026-09-05T00:00:00Z", + OpenIssues: 2, ClosedIssues: 5}, + }, + }, + openIssues: map[string][]Issue{ + // agents MVP：一個未分派 issue、一個未分派 PR、一個已分派 issue。 + "alterminal/agents?milestone=MVP": { + {Number: 31, Title: "總覽命令", State: "open", + UpdatedAt: "2026-09-10T01:00:00Z", + Repository: &Repository{FullName: "alterminal/agents"}, + HTMLURL: "https://gitea.alterminal.com/alterminal/agents/issues/31"}, + {Number: 32, Title: "文件", State: "open", + UpdatedAt: "2026-09-08T00:00:00Z", + Repository: &Repository{FullName: "alterminal/agents"}, + HTMLURL: "https://gitea.alterminal.com/alterminal/agents/pulls/32", + PullRequest: &pullMarker{}, User: &User{UserName: "alex"}}, + {Number: 33, Title: "已分派", State: "open", + UpdatedAt: "2026-09-07T00:00:00Z", + Repository: &Repository{FullName: "alterminal/agents"}, + HTMLURL: "https://gitea.alterminal.com/alterminal/agents/issues/33", + Assignee: &User{UserName: "queena"}}, + }, + // agents v1（無期限）：條目比里程碑本身新 → updated_at 取條目。 + "alterminal/agents?milestone=v1": { + {Number: 40, Title: "無人理", State: "open", + UpdatedAt: "2026-09-09T23:30:00Z", + Repository: &Repository{FullName: "alterminal/agents"}, + HTMLURL: "https://gitea.alterminal.com/alterminal/agents/issues/40"}, + }, + }, + } +} + +// TestMilestoneOverviewSortAndOverdue 驗證排序（期限近者在前、無期限在後） +// 與 overdue／due_hours 計算。 +func TestMilestoneOverviewSortAndOverdue(t *testing.T) { + now := time.Date(2026, 9, 10, 8, 0, 0, 0, time.UTC) + entries, err := MilestoneOverview(newMilestoneFixture(), "https://gitea.alterminal.com", now) + if err != nil { + t.Fatalf("MilestoneOverview: %v", err) + } + if len(entries) != 3 { + t.Fatalf("應有 3 筆（空倉庫跳過），得到 %d", len(entries)) + } + // 排序：MVP（2026-09-09，已過期）→ CLI（2026-09-12）→ v1（無期限）。 + wantOrder := []string{"alterminal/agents#MVP", "alterminal/teai#CLI", "alterminal/agents#v1"} + for i, want := range wantOrder { + got := entries[i].Repo + "#" + entries[i].Title + if got != want { + t.Errorf("第 %d 筆應為 %s，得到 %s", i, want, got) + } + } + // MVP：due 2026-09-09T00:00Z、now 09-10T08:00Z → 32 小時、逾期。 + if !entries[0].Overdue { + t.Errorf("MVP 應逾期") + } + if entries[0].DueHours == nil || *entries[0].DueHours != 32.0 { + t.Errorf("MVP due_hours 應 32.0，得到 %v", entries[0].DueHours) + } + // CLI：未到期。 + if entries[1].Overdue { + t.Errorf("CLI 不應逾期") + } + // v1：無期限 → null。 + if entries[2].DueOn != nil || entries[2].DueHours != nil || entries[2].Overdue { + t.Errorf("v1 無期限應為 null/false，得到 %+v", entries[2]) + } +} + +// TestMilestoneOverviewUnassigned 驗證未分派條目摘要（issue 無 author、 +// pull 帶 author）與 updated_at 取最大值。 +func TestMilestoneOverviewUnassigned(t *testing.T) { + now := time.Date(2026, 9, 10, 8, 0, 0, 0, time.UTC) + entries, err := MilestoneOverview(newMilestoneFixture(), "https://gitea.alterminal.com", now) + if err != nil { + t.Fatalf("MilestoneOverview: %v", err) + } + var mvp *MilestoneEntry + for i := range entries { + if entries[i].Title == "MVP" { + mvp = &entries[i] + } + } + if mvp == nil { + t.Fatalf("找不到 MVP") + } + // 未分派：#31（issue）、#32（PR, author=alex）；#33 已分派不列。 + if len(mvp.Unassigned) != 2 { + t.Fatalf("MVP 應有 2 筆未分派，得到 %d：%+v", len(mvp.Unassigned), mvp.Unassigned) + } + if mvp.Unassigned[0].Type != "issue" || mvp.Unassigned[0].Number != 31 { + t.Errorf("第一筆未分派應為 issue #31，得到 %+v", mvp.Unassigned[0]) + } + if mvp.Unassigned[1].Type != "pull" || mvp.Unassigned[1].Number != 32 || mvp.Unassigned[1].Author != "alex" { + t.Errorf("第二筆未分派應為 pull #32（author=alex），得到 %+v", mvp.Unassigned[1]) + } + // updated_at：max(里程碑 09-01, #31 09-10T01:00Z) → 後者。 + if mvp.UpdatedAt == nil || *mvp.UpdatedAt != "2026-09-10T01:00:00+00:00" { + t.Errorf("MVP updated_at 應取條目最大值 2026-09-10T01:00:00+00:00，得到 %v", mvp.UpdatedAt) + } + // url 組法。 + if mvp.URL != "https://gitea.alterminal.com/alterminal/agents/milestone/7" { + t.Errorf("MVP url 應為 milestone/7，得到 %s", mvp.URL) + } +} + +// TestMilestoneOverviewJSONKeys 驗證 JSON 鍵集與鍵序與 gitea.py 一致， +// 以及 null／陣列空表示（unassigned 空 → []）。 +func TestMilestoneOverviewJSONKeys(t *testing.T) { + now := time.Date(2026, 9, 10, 8, 0, 0, 0, time.UTC) + entries, err := MilestoneOverview(newMilestoneFixture(), "", now) + if err != nil { + t.Fatalf("MilestoneOverview: %v", err) + } + // v1：無期限、無未分派條目 → due_on/due_hours/updated_at 的 null 表示、 + // unassigned=[]、webBase 空 → url=""。 + var v1 *MilestoneEntry + for i := range entries { + if entries[i].Title == "v1" { + v1 = &entries[i] + } + } + if v1 == nil { + t.Fatalf("找不到 v1") + } + // 手寫期望 JSON（縮排 2、鍵序照 gitea.py dict 實字序）。 + b, err := json.Marshal(v1) + if err != nil { + t.Fatalf("Marshal: %v", err) + } + // 以逐鍵比對為準（MarshalIndent 因自訂 MarshalJSON 不縮排內層）。 + var obj map[string]json.RawMessage + if err := json.Unmarshal(b, &obj); err != nil { + t.Fatalf("Unmarshal: %v", err) + } + wantKeys := []string{"repo", "id", "title", "url", "open_issues", "closed_issues", + "due_on", "due_hours", "overdue", "unassigned", "updated_at"} + // 鍵序：json.Unmarshal 到 map 會失序；改檢查原始字串的鍵出現順序。 + pos := -1 + for _, k := range wantKeys { + i := strings.Index(string(b), `"`+k+`":`) + if i < 0 { + t.Fatalf("輸出缺少鍵 %q：%s", k, b) + } + if i < pos { + t.Fatalf("鍵 %q 順序錯誤：%s", k, b) + } + pos = i + } + for _, kv := range []struct { + key string + want string + }{ + {"repo", `"alterminal/agents"`}, + {"due_on", `null`}, + {"due_hours", `null`}, + {"overdue", `false`}, + {"url", `""`}, + } { + if got := string(obj[kv.key]); got != kv.want { + t.Errorf("%s 應為 %s，得到 %s", kv.key, kv.want, got) + } + } + if !strings.Contains(string(b), `"number":40`) { + t.Errorf("未分派條目應含 number 40：%s", b) + } + // pull 條目的 author 鍵：有作者才輸出（無則不該出現 "author"）。 + if strings.Contains(string(obj["unassigned"]), `"author"`) { + t.Errorf("issue 條目不應有 author 鍵：%s", obj["unassigned"]) + } +} + +// TestMilestoneOverviewDueHoursRounding 驗證 due_hours 捨入到一位小數， +// 且 overdue 以未捨入值判定（0.04h → 0.0 但 overdue=true）。 +func TestMilestoneOverviewDueHoursRounding(t *testing.T) { + src := &fakeMilestoneSource{ + orgs: []string{"alterminal"}, + repos: map[string][]Repo{"alterminal": {{Name: "r"}}}, + milestones: map[string][]Milestone{ + "alterminal/r": { + {ID: idPtr(1), Title: "edge", State: "open", + DueOn: msPtr("2026-09-10T07:57:36Z"), UpdatedAt: "2026-09-10T07:00:00Z"}, + }, + }, + openIssues: map[string][]Issue{}, + } + now := time.Date(2026, 9, 10, 8, 0, 0, 0, time.UTC) + entries, err := MilestoneOverview(src, "", now) + if err != nil { + t.Fatalf("MilestoneOverview: %v", err) + } + if len(entries) != 1 { + t.Fatalf("應有 1 筆，得到 %d", len(entries)) + } + // 144 秒 = 0.04 小時 → round1 → 0.0；未捨入 > 0 → overdue=true。 + b, err := json.Marshal(entries[0]) + if err != nil { + t.Fatalf("Marshal: %v", err) + } + if !strings.Contains(string(b), `"due_hours":0.0`) { + t.Errorf("due_hours 應捨入為 0.0：%s", b) + } + if !strings.Contains(string(b), `"overdue":true`) { + t.Errorf("overdue 應以未捨入值判定為 true：%s", b) + } +} -- 2.54.0