forge

type Backlog interface {
	// Issues lists the open issues, merge requests left out, by number.
	Issues() ([]Issue, error)
	// Comments lists the comments on t, oldest first.
	Comments(t Target) ([]string, error)
	// Close closes an issue: as a duplicate of dup when dup > 0, else as
	// completed. Closing one already closed changes nothing.
	Close(id, dup int) error
	// Milestones lists the titles of the open milestones.
	Milestones() ([]string, error)
	// SetMilestone puts an issue in the open milestone with this title,
	// creating it when there is none.
	SetMilestone(id int, title string) error
	// SetBody rewrites an issue's body.
	SetBody(id int, body string) error
	// EnsureLabel creates a label when the project has none of that name,
	// so a person finds it in the forge's list to set.
	EnsureLabel(name, color, description string) error
}

type Fake struct{ Path string }

type FakeItem struct {
	ID        int      `json:"id"`
	Branch    string   `json:"branch,omitempty"` // a merge request's source branch
	Base      string   `json:"base,omitempty"`
	Closed    bool     `json:"closed,omitempty"`
	Reason    string   `json:"reason,omitempty"` // why it was closed: completed or duplicate
	Milestone string   `json:"milestone,omitempty"`
	Fork      bool     `json:"fork,omitempty"` // a merge request from a fork
	Title     string   `json:"title,omitempty"`
	Body      string   `json:"body,omitempty"`
	Labels    []string `json:"labels"`
	Comments  []string `json:"comments"`
	Author    string   `json:"author,omitempty"`
	Insider   bool     `json:"insider,omitempty"`
}

type FakeState struct {
	Issues        []FakeItem `json:"issues"`
	MergeRequests []FakeItem `json:"merge-requests"`
	Milestones    []string   `json:"milestones,omitempty"`    // open milestones, by title
	Labels        []FakeItem `json:"labels,omitempty"`        // labels defined, their name as id
	FailOnWrite   int        `json:"fail-on-write,omitempty"` // the write that fails, counting from 1
	Writes        int        `json:"writes"`
}

type Forge interface {
	Issue(id int) (*Issue, error)
	// Comment posts body on t unless a comment carrying marker is already there.
	Comment(t Target, body, marker string) error
	// Sticky keeps one comment carrying marker on t, edited to body on each
	// run instead of a new one each time; with create false, it only edits
	// one already there.
	Sticky(t Target, body, marker string, create bool) error
	// Label adds and removes labels; adding one already there changes nothing.
	Label(t Target, add, remove []string) error
	// OpenIssue creates an issue, or comments on an open one with the same title.
	OpenIssue(title, body, marker string) (int, error)
	// KeepIssue rewrites the body of the open issue with this title, or opens
	// it when there is none and create is true: one issue, kept in place.
	KeepIssue(title, body string, create bool) (int, error)
	// OpenMergeRequest opens a merge request from branch into base, or
	// updates the title and body of the one already open from branch.
	OpenMergeRequest(branch, base, title, body string) (int, error)
	// OpenMergeRequests lists the branches of the open merge requests whose
	// branch starts with prefix, sorted.
	OpenMergeRequests(prefix string) ([]string, error)
	// MergeRequest says where a merge request comes from and goes.
	MergeRequest(id int) (MergeRequest, error)
}

type Issue struct {
	ID        int      `json:"id"`
	Title     string   `json:"title"`
	Body      string   `json:"body"`
	Labels    []string `json:"labels"`
	Closed    bool     `json:"closed,omitempty"`
	Milestone string   `json:"milestone,omitempty"` // the title of the milestone it is in, if any
	Author    string   `json:"author,omitempty"`    // who opened it
	Insider   bool     `json:"insider,omitempty"`   // its author has write access to the project; false when the forge does not say
}

type Local struct{ Repo string }

type LocalItem struct {
	ID        int      `yaml:"-"`
	Title     string   `yaml:"title"`
	State     string   `yaml:"state"` // open or closed, as written; see Local.StateOf
	Labels    []string `yaml:"labels,flow"`
	Milestone string   `yaml:"milestone,omitempty"`
	Branch    string   `yaml:"branch,omitempty"` // a merge request's local branch
	Base      string   `yaml:"base,omitempty"`
	Body      string   `yaml:"-"`
	Comments  []string `yaml:"-"`
}

type MergeRequest struct {
	Branch string // the branch it comes from
	Base   string // the branch it goes into; "" when the forge does not say
	Here   bool   // the branch lives in this repository, not in a fork
}

type Target struct {
	Kind string `json:"kind" yaml:"kind"` // "issue" or "merge-request"
	ID   int    `json:"id" yaml:"id"`
}