mesh-catalog/modules/mesh-delivery/cmd/mesh-delivery/ready.go

package main

import (
	"fmt"
	"strings"
	"time"
)

// Merge on ready (novox/hq issue 722).
//
// The operator, 2026-10-14: "the reviewer task should merge the request or mark the MR as ready to merge in any case".
// Before, a reviewed pull request with green checks waited until a session called the forge's merge tool, and again
// after every check the tool asked because the trunk had moved. Now the independent reviewer marks the pull request
// ready at the head it approved — the forge label `mesh/ready` and a comment "ready at <full head sha>" (approving
// through the forge is the operator's) — and this owner merges it, through the forge's own merge tool
// (gitea_merge_pull_request), the one path every merge takes:
//
//   - only at the head the mark names, and only while that is the pull request's head: a push after the mark clears
//     it — the label taken off, and said on the pull request — and the new head needs a mark of its own;
//   - only when its delivery is ready here: its check passed against its trunk's head. A verdict out of date is judged
//     again by the merge tool, which asks the check against the trunk's head itself (novox/hq ADR 0323 §5); the merge
//     is asked again once a minute, and lands on the passing verdict;
//   - a group member only at its turn in the group's order, and only once the group's composed check passed for its
//     members' heads as they are;
//   - a check that failed merges nothing: it is said once on the pull request, and as a stalled line, which the
//     controller raises as the condition `delivery.<id>.stalled`. So is a mark the merge tool refused for an hour.
//
// What this owner does with a mark is kept on the delivery (Ready), said in its log, and the merge's transitions name
// it as their author.

// ReadyMark is a pull request's ready mark as the forge reads it (the gitea module's gitea_open_pulls): the head the
// newest "ready at" comment names, who wrote it and when, and the label's id. Head is empty when the label is on and
// no comment names a head.
type ReadyMark struct {
	Head    string `json:"head"`
	By      string `json:"by,omitempty"`
	At      string `json:"at,omitempty"`
	LabelID int    `json:"label_id"`
}

// ReadyLabel is the label that marks a pull request ready.
const ReadyLabel = "mesh/ready"

// readyTryEvery is how often a marked head's merge is asked while the merge tool refuses it: a check it asked takes
// minutes, and a refusal costs the forge a few reads.
const readyTryEvery = time.Minute

// readyRefusedFor is how long the merge tool may refuse a marked head before it is said as stalled: longer than a
// check takes (the controller's checkTimeout is 45 minutes), so a check on its way is never said.
const readyRefusedFor = time.Hour

// ReadyRun is what this owner did with a delivery's ready mark: kept on the delivery and shown whole by `show`.
type ReadyRun struct {
	// Head, By and MarkedAt are the mark: the head it names, who marked it, when.
	Head     string `json:"head"`
	By       string `json:"by,omitempty"`
	MarkedAt string `json:"marked_at,omitempty"`
	// Seen is when this owner first read the mark.
	Seen time.Time `json:"seen"`
	// Waits is what the merge waits on, when it waits: a verdict, the group's turn or its composed check.
	Waits string `json:"waits,omitempty"`
	// Tries is how many times the merge was asked; LastTry when, and Answer what the merge tool last answered.
	Tries   int       `json:"tries,omitempty"`
	LastTry time.Time `json:"last_try"`
	Answer  string    `json:"answer,omitempty"`
	// RefusedSince is when the merge tool began refusing it without a break.
	RefusedSince *time.Time `json:"refused_since,omitempty"`
	// Merged is when the merge tool merged it.
	Merged *time.Time `json:"merged,omitempty"`
	// Failed is why it is not merged and will not be on this head: its check failed. Said once on the pull request.
	Failed string `json:"failed,omitempty"`
}

// mergedBy is who a merge this owner made on a ready mark is said to be by, in its transitions.
func (r *ReadyRun) mergedBy() string {
	if r == nil || r.Merged == nil {
		return ""
	}
	by := byOwner + ", on the ready mark at " + shortOf(r.Head, 12)
	if r.By != "" {
		by += " by " + r.By
	}
	return by
}

// marked is a pull request read with a ready mark.
type marked struct {
	pull OpenPull
	// cleared is when the mark was cleared, the label taken off: not cleared again within readyTryEvery.
	cleared time.Time
}

// pullKey is a pull request as a key: owner/repo#number.
func pullKey(p OpenPull) string {
	return strings.ToLower(p.Owner+"/"+p.Repo) + fmt.Sprintf("#%d", p.Number)
}

// seeMarks keeps the open pull requests that carry a ready mark; under the lock. A pull request no longer open or
// no longer marked drops out.
func (h *Holder) seeMarks(open []OpenPull) {
	seen := map[string]*marked{}
	for _, p := range open {
		if p.Ready == nil || p.HeadSHA == "" {
			continue
		}
		k := pullKey(p)
		m := &marked{pull: p}
		if was := h.marks[k]; was != nil && was.pull.Ready != nil && was.pull.Ready.Head == p.Ready.Head &&
			was.pull.HeadSHA == p.HeadSHA {
			m.cleared = was.cleared
		}
		seen[k] = m
	}
	h.marks = seen
}

// sameFull is whether a mark names a head: the whole sha, or — read from an older forge module — at least twelve
// characters of it.
func sameFull(mark, head string) bool {
	mark, head = strings.ToLower(mark), strings.ToLower(head)
	return len(mark) >= 12 && strings.HasPrefix(head, mark)
}

// readyAsks works out, under the lock, what each ready mark needs: a mark cleared, a merge asked, a failure said.
// The asking happens outside the lock.
func (h *Holder) readyAsks(now time.Time) []func() {
	var asks []func()
	for k, m := range h.marks {
		p, mark := m.pull, *m.pull.Ready
		repository := strings.ToLower(p.Owner + "/" + p.Repo)
		if !sameFull(mark.Head, p.HeadSHA) {
			if !m.cleared.IsZero() && now.Sub(m.cleared) < readyTryEvery {
				continue
			}
			m.cleared = now
			asks = append(asks, h.clearMark(k, p, mark))
			continue
		}
		d := h.deliveries[IDOf(repository, p.HeadSHA)]
		if d == nil || d.State.Final() || d.MergedAs != "" {
			continue // not announced yet, or past its merge
		}
		if d.Ready == nil || d.Ready.Head != mark.Head {
			d.Ready = &ReadyRun{Head: mark.Head, By: mark.By, MarkedAt: mark.At, Seen: now}
			h.Logf("[mesh-delivery] %s is marked ready at %s by %s: merged once its check passes against its trunk's head",
				d.ID, shortOf(mark.Head, 12), orNone(mark.By))
			h.keep(d)
		}
		r := d.Ready
		if r.Merged != nil {
			continue
		}
		if d.State == Rejected {
			if r.Failed == "" {
				r.Failed = "its check failed"
				if d.Check != nil {
					r.Failed += ": " + oneLine(d.Check.Summary)
					if j := d.Check.Judged(); j != "" {
						r.Failed += " (" + j + ")"
					}
				}
				r.Waits = ""
				h.Logf("[mesh-delivery] %s is marked ready and not merged: %s", d.ID, r.Failed)
				h.keep(d)
				asks = append(asks, h.sayOn(d, fmt.Sprintf("mesh-delivery: **not merged.** This pull request is marked "+
					"ready at %s, and %s. A new head, marked ready once reviewed, or a recheck that passes, merges it.",
					mark.Head, r.Failed)))
			}
			continue
		}
		r.Failed = ""
		waits := h.readyWaits(d)
		if waits != r.Waits {
			r.Waits = waits
			if waits != "" {
				h.Logf("[mesh-delivery] %s is marked ready and waits: %s", d.ID, waits)
			}
			h.keep(d)
		}
		if waits != "" || (!r.LastTry.IsZero() && now.Sub(r.LastTry) < readyTryEvery) {
			continue
		}
		r.Tries++
		r.LastTry = now
		h.keep(d)
		asks = append(asks, h.askMerge(d.ID, p, mark.Head))
	}
	return asks
}

// readyWaits is what a marked delivery's merge waits on; empty when it is asked now. A ready delivery is asked; so is
// a proposed one whose verdict went out of date and whose check nobody asked again — the merge tool asks it.
func (h *Holder) readyWaits(d *Delivery) string {
	switch {
	case d.State == Ready:
	case d.State == Proposed && d.outOfDate() != "" && d.AskedAgain == nil:
	case d.State == Proposed && d.AskedAgain != nil:
		return "its check against the trunk's head is asked and has not answered"
	default:
		return "its check has not passed yet (" + string(d.State) + ")"
	}
	if d.Group == "" {
		return ""
	}
	return h.groupTurnToMerge(d)
}

// groupTurnToMerge is why a group member may not merge yet; empty at its turn: the group's composed check passed for
// its members' heads as they are and is not out of date, and every member before it in the group's order merged.
func (h *Holder) groupTurnToMerge(d *Delivery) string {
	g := h.groups[d.Group]
	if g == nil {
		return ""
	}
	members := h.membersOf(g)
	if state, why := GroupState(g, members); state != "ready" && state != "delivering" {
		return fmt.Sprintf("its group %s is %s: %s", g.ID, state, why)
	}
	if c := g.Check; c == nil || (c.Verdict != "pass" && c.Verdict != "warning") || c.OutOfDate != "" ||
		!sameMembers(c.Commits, commitsOf(members)) {
		return "its group " + g.ID + "'s composed check has not passed for its members' heads"
	}
	if !containsString(g.Order, d.ID) {
		return "its group " + g.ID + "'s order is not worked out for it yet"
	}
	for _, id := range g.Order {
		if id == d.ID {
			return ""
		}
		if o := h.deliveries[id]; o != nil && o.MergedAs == "" && !o.State.Final() {
			return "its group " + g.ID + "'s order merges " + id + " first"
		}
	}
	return ""
}

// askMerge asks the forge's merge tool to merge a marked head, and keeps its answer.
func (h *Holder) askMerge(id string, p OpenPull, head string) func() {
	return func() {
		err := h.Forge.Merge(p.Owner, p.Repo, p.Number, head)
		h.mu.Lock()
		defer h.mu.Unlock()
		d := h.deliveries[id]
		if d == nil || d.Ready == nil {
			return
		}
		r, now := d.Ready, h.Now()
		if err == nil {
			r.Merged, r.Answer, r.RefusedSince = &now, "merged", nil
			h.Logf("[mesh-delivery] %s merged on its ready mark at %s, its check passed against its trunk's head", id,
				shortOf(head, 12))
			h.keep(d)
			return
		}
		answer := oneLine(err.Error())
		if r.RefusedSince == nil {
			r.RefusedSince = &now
		}
		if answer != r.Answer {
			h.Logf("[mesh-delivery] %s is marked ready, and the merge tool did not merge it (asked again in %s): %s", id,
				readyTryEvery, answer)
		}
		r.Answer = answer
		h.keep(d)
	}
}

// clearMark takes a mark off a pull request whose head moved after it, and says so on it.
func (h *Holder) clearMark(k string, p OpenPull, mark ReadyMark) func() {
	return func() {
		err := h.Forge.Unlabel(p.Owner, p.Repo, p.Number, mark.LabelID)
		if err == nil {
			err = h.Forge.Comment(p.Owner, p.Repo, p.Number, fmt.Sprintf("mesh-delivery: the ready mark at %s is cleared: "+
				"the head is now %s, pushed after it. Mark the new head ready once it is reviewed.", mark.Head, p.HeadSHA))
		}
		if err != nil {
			h.Logf("[mesh-delivery] %s's ready mark at %s names an older head than %s, and could not be cleared yet: %v",
				k, shortOf(mark.Head, 12), shortOf(p.HeadSHA, 12), err)
			return
		}
		h.Logf("[mesh-delivery] %s's ready mark at %s cleared: its head is now %s", k, shortOf(mark.Head, 12),
			shortOf(p.HeadSHA, 12))
		h.mu.Lock()
		delete(h.marks, k)
		h.mu.Unlock()
	}
}

// sayOn comments on a delivery's pull request.
func (h *Holder) sayOn(d *Delivery, body string) func() {
	owner, repo, number, id := d.Owner(), d.Repo(), d.Number, d.ID
	return func() {
		if err := h.Forge.Comment(owner, repo, number, body); err != nil {
			h.Logf("[mesh-delivery] %s: could not say on its pull request: %v", id, err)
		}
	}
}

// readyLines are the marked heads that will not merge: a check that failed at once, a merge refused past its bound;
// as stalled lines, which the controller raises as conditions. Under the lock.
func (h *Holder) readyLines(now time.Time) []StalledLine {
	var out []StalledLine
	for _, d := range h.deliveries {
		r := d.Ready
		if r == nil || r.Merged != nil || d.MergedAs != "" || d.State.Final() {
			continue
		}
		switch {
		case r.Failed != "" && d.State == Rejected:
			out = append(out, StalledLine{ID: d.ID, Number: d.Number, State: d.State, For: now.Sub(r.Seen).Round(time.Second).String(),
				Bound: "0s", H2: "none: a new head marked ready, or a recheck that passes — the operator's",
				Says: fmt.Sprintf("%s#%d is marked ready at %s and not merged: %s", d.Repository, d.Number,
					shortOf(r.Head, 12), r.Failed)})
		case r.RefusedSince != nil && now.Sub(*r.RefusedSince) >= readyRefusedFor:
			out = append(out, StalledLine{ID: d.ID, Number: d.Number, State: d.State,
				For: now.Sub(*r.RefusedSince).Round(time.Second).String(), Bound: readyRefusedFor.String(),
				H2: "none: the merge is asked again each minute — the operator's",
				Says: fmt.Sprintf("%s#%d is marked ready at %s, and the merge tool has refused it since %s: %s", d.Repository,
					d.Number, shortOf(r.Head, 12), r.RefusedSince.UTC().Format(time.RFC3339), r.Answer)})
		}
	}
	return out
}