forge

type Backlog interface {
	// Issues lists the open issues, merge requests left out, by number,
	// each with the issues it waits on in the forge's own relation.
	Issues() ([]Issue, error)
	// AllIssues lists the issues open and closed, merge requests left out,
	// by number: a subject a role found is looked for in both (OpenOnce).
	AllIssues() ([]Issue, error)
	// Comments lists the comments on t, oldest first.
	Comments(t Target) ([]string, error)
	// Notes lists the comments on t with their authors, oldest first, as
	// Comments does.
	Notes(t Target) ([]Note, 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 open milestones, with their due dates.
	Milestones() ([]Milestone, 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
	// SetTitle renames an issue.
	SetTitle(id int, title string) error
	// AddSubIssue makes child a sub-issue of parent where the forge has
	// sub-issues, and says so; false on a forge that has none, the child
	// then listed in the parent's body by the caller. Adding one already
	// there changes nothing.
	AddSubIssue(parent, child int) (bool, error)
	// AddBlocker records that id waits on blocker in the forge's own
	// relation, and says so; false on a forge that has none — the caller
	// then writes a line in the body (ADR-0028). Adding one already there
	// changes nothing.
	AddBlocker(id, blocker int) (bool, error)
	// RemoveBlocker takes blocker off what id waits on in the forge's own
	// relation; one not there, or a forge without the relation, changes
	// nothing. Only the role's own links are taken off (ADR-0028).
	RemoveBlocker(id, blocker int) error
	// Closers lists what closed an issue, as the forge links it: the pull
	// or merge request, or the commit; nil when the forge does not say.
	Closers(id int) ([]Closer, error)
	// Ticks lists the boxes ticked and unticked in an issue's body, oldest
	// first, with who did each; nil when the forge does not say.
	Ticks(id int) ([]Tick, error)
	// Trail says when an open issue last got a label, and what pull or
	// merge requests and commits name it; an empty Labeled when the
	// forge does not say (ADR-0031).
	Trail(id int, label string) (Trail, 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 Closer struct {
	Kind string `json:"kind"`           // pull-request (a GitHub pull request, a GitLab merge request) or commit
	Ref  string `json:"ref"`            // how the forge names it: "#20", "!7", a short commit
	Text string `json:"text,omitempty"` // its title and description, or the commit's message
}

type Fake struct{ Path string }

type FakeComment Note

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, not_planned 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  []FakeComment `json:"comments"`
	Author    string        `json:"author,omitempty"`
	Insider   bool          `json:"insider,omitempty"`
	Parent    int           `json:"parent,omitempty"`     // the issue it is a sub-issue of
	BlockedBy []int         `json:"blocked-by,omitempty"` // the issues it waits on, in the forge's own relation
	Ticks     []Tick        `json:"ticks,omitempty"`      // boxes ticked in its body, with who ticked them
	ClosedBy  []Closer      `json:"closed-by,omitempty"`  // what closed it: a pull request, a commit
	// Labeled says when it last got each label; Links, what names it
	// (Trail, ADR-0031).
	Labeled map[string]string `json:"labeled,omitempty"`
	Links   []Link            `json:"links,omitempty"`
}

type FakeState struct {
	Issues        []FakeItem `json:"issues"`
	MergeRequests []FakeItem `json:"merge-requests"`
	Milestones    []string   `json:"milestones,omitempty"` // open milestones, by title
	// MilestoneDue gives a milestone its due date, YYYY-MM-DD, by title.
	MilestoneDue map[string]string `json:"milestone-due,omitempty"`
	Labels       []FakeItem        `json:"labels,omitempty"`        // labels defined, their name as id
	SubIssues    bool              `json:"sub-issues,omitempty"`    // the forge has sub-issues, as GitHub
	Dependencies bool              `json:"dependencies,omitempty"`  // the forge has a blocked-by relation, as GitHub
	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"`
	Reason    string   `json:"reason,omitempty"`    // why it was closed, when the forge says: completed, not_planned, duplicate
	Milestone string   `json:"milestone,omitempty"` // the title of the milestone it is in, if any
	// MilestoneDue is its milestone's due date, YYYY-MM-DD, when it has
	// one: the backlog's order ranks milestones by it (Milestone).
	MilestoneDue string `json:"milestone-due,omitempty"`
	Author       string `json:"author,omitempty"`  // who opened it
	Insider      bool   `json:"insider,omitempty"` // its author is a person of the project (GitHub: owner, member, collaborator; GitLab: Planner or above); false when the forge does not say
	// BlockedBy are the issues it waits on in the forge's own relation
	// (GitHub's dependencies, GitLab's is_blocked_by), open or closed, as
	// Issues gives them; a line in its body says the rest (ADR-0028).
	BlockedBy []int `json:"blocked-by,omitempty"`
	// Children are its sub-issues in the forge's own relation (GitHub's
	// sub-issues, GitLab's tasks), open or closed, as Issues gives them; a
	// task list under "## Sub-issues" in its body says the rest (ADR-0029).
	Children []int `json:"children,omitempty"`
}

type Link struct {
	Kind string `json:"kind"`         // pull-request (a GitHub pull request, a GitLab merge request) or commit
	Ref  string `json:"ref"`          // how the forge names it: "#20", "!7", a short commit
	At   string `json:"at,omitempty"` // when it named the issue, RFC 3339 or YYYY-MM-DD
}

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
	Title  string // what its author calls it
	Body   string // what its author says of it: testimony for a review (ADR-0020)
}

type Milestone struct {
	Title string `json:"title"`
	Due   string `json:"due,omitempty"`
}

type Note struct {
	Body    string `json:"body"`
	Author  string `json:"author,omitempty"`  // who wrote it; "" when the forge does not say
	Insider bool   `json:"insider,omitempty"` // its author is a person of the project, as Issue.Insider
	Bot     bool   `json:"bot,omitempty"`     // its author is a bot: a token's user, an app
	Created string `json:"created,omitempty"` // when it was written, RFC 3339 or YYYY-MM-DD; "" when the forge does not say
}

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

type Tick struct {
	Item string `json:"item"`           // the item's text, as the forge gives it: its hidden markers' text in it
	Done bool   `json:"done,omitempty"` // ticked; false: unticked
	Note        // its author: Author, Insider, Bot; no author and not Insider when the forge does not say
}

type Trail struct {
	Labeled string `json:"labeled,omitempty"` // when it last got the label, RFC 3339 or YYYY-MM-DD; "" when the forge does not say
	Links   []Link `json:"links,omitempty"`
}