teai/internal/workflow/milestones.go

// 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)
}