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)
	// 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
	// LabelEvents lists the labels set on an issue and taken off, oldest
	// first, with who did each and when; nil when the forge does not say
	// (ADR-0038).
	LabelEvents(id int) ([]LabelEvent, error)
	// React puts a reaction (Eyes) on a comment of an issue, by the note's
	// ID; one there already changes nothing, nor does a forge without
	// reactions (ADR-0038).
	React(id int, note, emoji 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, Repo 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
	Bot       bool          `json:"bot,omitempty"`  // a merge request a bot opened: an app, a token's user
	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
	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"`
	// LabelEvents are its labels set and taken off, with who; Reactions,
	// the reactions on its comments, by the comment's id (ADR-0038).
	LabelEvents []LabelEvent        `json:"label-events,omitempty"`
	Reactions   map[string][]string `json:"reactions,omitempty"`
	// Threads are a merge request's comments on lines, as a review leaves
	// them (LineReviewer).
	Threads []FakeThread `json:"threads,omitempty"`
	// A merge request's state for the merge policy (MergeState, ADR-0042):
	// a draft; its auto-merge on, when it was last turned on and by whom;
	// its head's checks; its branch's pushes, each head a revision of the
	// repository. Clean: the forge would merge it at once, its rules met,
	// so turning auto-merge on merges it (Merged).
	Draft       bool       `json:"draft,omitempty"`
	AutoMerge   bool       `json:"auto-merge,omitempty"`
	AutoMergeAt string     `json:"auto-merge-at,omitempty"`
	AutoMergeBy string     `json:"auto-merge-by,omitempty"`
	Checks      string     `json:"checks,omitempty"`
	Pushes      []FakePush `json:"pushes,omitempty"`
	Clean       bool       `json:"clean,omitempty"`
	Merged      bool       `json:"merged,omitempty"`
}

type FakePush struct {
	Head string `json:"head"`
	At   string `json:"at"`
}

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
	// Scoped: its labels are scoped, `key::value`, as GitLab's (ADR-0038).
	Scoped      bool `json:"scoped-labels,omitempty"`
	FailOnWrite int  `json:"fail-on-write,omitempty"` // the write that fails, counting from 1
	Writes      int  `json:"writes"`
	// ReviewRefused: the forge refuses every comment on a line, as a
	// token that may not review does, with this reason (HTTP 403).
	ReviewRefused string `json:"review-refused,omitempty"`
	Reviews       int    `json:"reviews,omitempty"` // the reviews posted, each holding comments on lines
	// JobToken: the token is a CI job's own, whose merges start no
	// pipeline, as GitHub's GITHUB_TOKEN (MergeToken, ADR-0042).
	JobToken bool `json:"job-token,omitempty"`
	// Unguarded: why a push after a yes could merge before follow takes
	// it back — a base not requiring workline/accepted (Guarded).
	Unguarded string `json:"unguarded,omitempty"`
	// Statuses are the statuses set on commits, as GitHub keeps them: the
	// commit a revision of the repository, who set it (`workline-bot`, the
	// token's user, or another).
	Statuses []FakeStatus `json:"statuses,omitempty"`
}

type FakeStatus struct {
	Commit      string `json:"commit"`
	Name        string `json:"name"`
	State       string `json:"state,omitempty"`
	Description string `json:"description,omitempty"`
	By          string `json:"by"`
}

type FakeThread struct {
	Path     string `json:"path"`
	Line     int    `json:"line"`
	Body     string `json:"body"`
	Resolved bool   `json:"resolved,omitempty"`
}

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)
	// CloseMergeRequest closes the open merge request from branch, saying
	// why in a comment carrying marker, posted once; with none open from
	// branch, it changes nothing. The branch stays.
	CloseMergeRequest(branch, body, marker string) error
	// MergeRequest says where a merge request comes from and goes.
	MergeRequest(id int) (MergeRequest, error)
	// ListMergeRequests lists the open merge requests, by number, each with
	// where it comes from and goes, and who opened it: what `workline
	// follow` needs to merge a base into a person's (ADR-0041).
	ListMergeRequests() ([]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 LabelEvent struct {
	Label string `json:"label"`
	Added bool   `json:"added,omitempty"` // set; false: taken off
	// Writer: who did it may push and merge — GitHub's write, maintain or
	// admin; GitLab's Developer or above —, the merge policy's yes
	// (ADR-0042); Insider, a person of the project, is wider on GitLab.
	Writer bool `json:"writer,omitempty"`
	Note
}

type LineComment struct {
	Path string `json:"path" yaml:"path"`
	Line int    `json:"line" yaml:"line"` // in the file at the head of the change
	// Key is what it says, hidden in it (Marker("line="+Key)): while a
	// comment holding it is open on the merge request, it is not posted
	// again; resolved, it is.
	Key  string `json:"key,omitempty" yaml:"key,omitempty"`
	Body string `json:"body" yaml:"body"`
}

type LineReviewer interface {
	Review(id int, head, body string, comments []LineComment) (Reviewed, error)
}

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 {
	ID     int    // its number; 0 when the forge does not say
	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)
	Author string // who opened it; "" when the forge does not say
	Bot    bool   // opened by a bot: an app, a token's user
	// Head is the ref this repository keeps its head under, for one from a
	// fork (GitHub's refs/pull/<n>/head); "" when the forge keeps none.
	Head string
	// Labels, Draft and AutoMerge are what ListMergeRequests reads of it
	// for the merge policy (ADR-0042): its labels, whether it is a draft,
	// whether the forge's auto-merge is on.
	Labels    []string
	Draft     bool
	AutoMerge bool
}

type MergeState struct {
	Head  string `json:"head"` // its head commit
	Draft bool   `json:"draft,omitempty"`
	// AutoMerge: the forge's auto-merge is on now. AutoMergeAt: when it
	// was last turned on, on now or not; "" never, or the forge does not
	// say. AutoMergeBy, AutoMergeBot: who turned it on now, and whether a
	// bot — workline's token, an app.
	AutoMerge    bool   `json:"auto-merge,omitempty"`
	AutoMergeAt  string `json:"auto-merge-at,omitempty"`
	AutoMergeBy  string `json:"auto-merge-by,omitempty"`
	AutoMergeBot bool   `json:"auto-merge-bot,omitempty"`
	// Checks: its head's checks as the forge sums them up — success,
	// pending, failure; "" none, or unread (ChecksUnread says why).
	Checks       string `json:"checks,omitempty"`
	ChecksUnread string `json:"checks-unread,omitempty"`
	// Labels are its labels set and taken off, oldest first, with who did
	// each, as Backlog's LabelEvents.
	Labels []LabelEvent `json:"label-events,omitempty"`
	// Pushes are the heads its branch was pushed to, oldest first; nil when
	// the forge does not say.
	Pushes []Push `json:"pushes,omitempty"`
}

type Merger interface {
	// MergeState reads an open merge request's state.
	MergeState(mr MergeRequest) (MergeState, error)
	// AutoMerge turns the forge's auto-merge on for the merge request at
	// head, or off. merged: the forge took it at once, its rules met
	// already (GitHub turns no auto-merge on for a pull request it could
	// merge now). Turning off one already off changes nothing.
	AutoMerge(mr MergeRequest, head string, on bool) (merged bool, err error)
	// Guarded says why a push after a person's yes could merge before
	// `follow` takes the yes back; "" when the forge holds it: GitHub when
	// the base requires the status Accepted, which a new head lacks;
	// GitLab, whose merge waits for the head's pipeline, `follow` in it.
	Guarded(base string) (string, error)
	// Accept marks a head accepted, or not, where the forge needs it to
	// hold a yes to that head only (GitHub: the status Accepted, by this
	// token); nothing where it does not.
	Accept(head string, ok bool, why string) error
	// KeepVerdict keeps the line's verdict on a head — its class, pass,
	// held, short or red, and why — where only this token writes it
	// (GitHub: the status VerdictStatus); Verdict reads it back, "" when
	// none is kept, or the forge keeps none (GitLab: the verdict is in hand
	// in the pipeline that judged the head).
	KeepVerdict(head, class, why string) error
	Verdict(head string) (class, why string, err error)
}

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
	// ID is the forge's own id of the comment, to put a reaction on it
	// (React); "" when the forge does not say.
	ID string `json:"id,omitempty"`
}

type Placed struct {
	LineComment
	State string `json:"state"`
	Why   string `json:"why,omitempty"`
}

type Push struct {
	Head string `json:"head"`
	At   string `json:"at"` // RFC 3339
}

type Reviewed struct {
	URL    string   `json:"url,omitempty"`
	Placed []Placed `json:"placed"`
}

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

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"`
}