forge

type Approvals struct {
	Required int
	Left     int
	By       []string
	// IHave and ICan are about the authenticated user: whether this account has
	// approved, and whether it is allowed to. Both providers refuse an author
	// approving their own work, so ICan is what decides between offering the
	// action and explaining why it is absent.
	IHave bool
	ICan  bool
}

type Caps struct {
	Suggestions          bool
	MultiLineSuggestions bool
	SuggestionStyle      SuggestionStyle
}

type DiffComment struct {
	Body             string
	OldPath, NewPath string
	Side             Side
	Line, StartLine  int
	Refs             DiffRefs
}

type DiffRefs struct {
	BaseSHA, HeadSHA, StartSHA string
}

type Epic struct {
	ID    string
	Title string
}

type FieldPatch struct {
	State *string
	// Labels and Assignees are the issue's complete new set: a nil slice
	// leaves them alone, a non-nil empty slice clears them.
	Labels    []string
	Assignees []string
	// Milestone is the milestone title; GitLab resolves it to an id before
	// writing.
	Milestone *string
	// Status is the work-item status name — GitLab's To do / In progress /
	// Done — set over GraphQL, since the REST issues endpoint has no field
	// for it. GitLab only.
	Status *string
	// Epic is the epic's title. GitLab only, group-level, licensed, and set
	// over GraphQL through the parent widget rather than a REST field.
	Epic *string
}

type Forge interface {
	// Capabilities reports what this provider will accept, so the UI can offer
	// only what will work rather than posting something that comes back
	// rejected.
	Capabilities() Caps
	// Whoami identifies the authenticated user.
	Whoami(ctx context.Context) (User, error)
	// Namespaces lists children of parent; parent "" lists top-level ones.
	Namespaces(ctx context.Context, parent string) ([]Namespace, error)
	// Repos lists projects directly inside namespace.
	Repos(ctx context.Context, namespace string) ([]Repo, error)
	// Issues lists issues in a project.
	Issues(ctx context.Context, ref Ref, f IssueFilter) ([]Issue, error)
	// Issue fetches one issue by its number.
	Issue(ctx context.Context, ref Ref, id int) (Issue, error)
	// GroupIssues lists issues across every project in a group, which is what
	// a group-level board shows.
	GroupIssues(ctx context.Context, group string, f IssueFilter) ([]Issue, error)
	// Labels, Milestones and Members are the values a board axis can take in a
	// project or a group — what a board needs to draw a lane before anything
	// is in it, and the name-to-id lookup a write needs to put something there.
	Labels(ctx context.Context, s Scope) ([]string, error)
	Milestones(ctx context.Context, s Scope) ([]Milestone, error)
	Members(ctx context.Context, s Scope) ([]User, error)
	// Statuses and Epics are the other two axes a board can group by. Both are
	// GitLab-only and both may be absent — an older instance, an edition
	// without epics — in which case they answer with nothing and no error, and
	// the axis simply does not appear. A transport or GraphQL failure
	// degrades exactly the same way, on purpose: a board legend that cannot
	// list statuses must still open.
	Statuses(ctx context.Context, s Scope) ([]Status, error)
	Epics(ctx context.Context, s Scope) ([]Epic, error)
	// StatusesStrict and EpicsStrict are Statuses and Epics' own listings, but
	// propagating a fetch failure instead of folding it into an empty list.
	// The status and epic pickers (internal/ui/board.go's pickStatus and
	// pickEpic) need the two told apart: their only way to say "nothing to
	// choose" is an empty list, so a transient failure answered the same way
	// would look exactly like a project with none — one enter away from
	// setting a field to something nobody chose. The board legend has no such
	// ambiguity to protect against and keeps calling Statuses/Epics.
	StatusesStrict(ctx context.Context, s Scope) ([]Status, error)
	EpicsStrict(ctx context.Context, s Scope) ([]Epic, error)
	// MergeRequests lists merge requests or pull requests in a project.
	MergeRequests(ctx context.Context, ref Ref, f MRFilter) ([]MergeRequest, error)
	// MergeRequest fetches one merge request by its number.
	MergeRequest(ctx context.Context, ref Ref, mr int) (MergeRequest, error)
	// MergeRequestDiff returns a merge request as a unified diff.
	MergeRequestDiff(ctx context.Context, ref Ref, mr int) (string, error)
	// Threads lists the discussions on an issue or merge request. target is
	// "issue/<id>" or "mr/<id>".
	Threads(ctx context.Context, ref Ref, target string) ([]Thread, error)
	// Tree lists the entries directly under a path in a repository. path ""
	// is the root; ref "" is the default branch.
	Tree(ctx context.Context, ref Ref, path, rev string) ([]TreeEntry, error)
	// FileContent returns a file's bytes.
	FileContent(ctx context.Context, ref Ref, path, rev string) ([]byte, error)
	// MyWork lists the current user's issues and merge requests across every
	// project they can see, in whichever roles the filter asks for.
	MyWork(ctx context.Context, f MyWorkFilter) ([]WorkItem, error)
	// Starred lists the current user's starred projects.
	Starred(ctx context.Context) ([]Repo, error)
	// Pipelines lists CI runs in a project.
	Pipelines(ctx context.Context, ref Ref, f PipelineFilter) ([]Pipeline, error)
	// Jobs lists the steps of one pipeline.
	Jobs(ctx context.Context, ref Ref, pipelineID int) ([]Job, error)
	// JobLog returns a job's log. The caller closes it.
	JobLog(ctx context.Context, ref Ref, jobID int) (io.ReadCloser, error)

	// Comment posts a note. target is "issue/<id>" or "mr/<id>".
	Comment(ctx context.Context, ref Ref, target, body string) error
	// CreateThread starts a new discussion, rather than replying to the main
	// one. Review comments want their own thread.
	CreateThread(ctx context.Context, ref Ref, target, body string) error
	// CreateDiffThread starts a discussion anchored to a place in the diff,
	// which is where a review comment belongs and the only place a suggestion
	// can be posted. It returns ErrNotPositioned when the anchor cannot be
	// honoured, so the caller can fall back to an ordinary thread and say so.
	CreateDiffThread(ctx context.Context, ref Ref, mr int, c DiffComment) error
	// SetFields applies a partial update to an issue or merge request.
	SetFields(ctx context.Context, ref Ref, target string, patch FieldPatch) error
	// RetryPipeline re-runs a pipeline's failed and canceled jobs.
	RetryPipeline(ctx context.Context, ref Ref, pipelineID int) error
	// Merge merges a merge request.
	Merge(ctx context.Context, ref Ref, mr int) error
	// Rebase brings a merge request up to date with its target branch,
	// through the provider's API rather than any local git.
	Rebase(ctx context.Context, ref Ref, mr int) error

	// Approvals reports who has approved a merge request and what it still
	// needs.
	Approvals(ctx context.Context, ref Ref, mr int) (Approvals, error)
	// Approve records the authenticated user's approval.
	Approve(ctx context.Context, ref Ref, mr int) error
	// Unapprove revokes it.
	Unapprove(ctx context.Context, ref Ref, mr int) error
	// SubmitReview publishes a whole review — the inline remarks, an optional
	// summary and a verdict — as one unit, so the author receives one
	// notification rather than one per remark.
	SubmitReview(ctx context.Context, ref Ref, mr int, r Review) (ReviewResult, error)
}

type Issue struct {
	// Ref names the project the issue belongs to. It matters for listings
	// that span projects, where a card has to say where it came from.
	Ref         Ref
	ID          int
	Title       string
	Description string
	State       string // "opened" | "closed"
	// Status is the provider work-item status, empty when it has none.
	Status    string
	Author    string
	Assignees []string
	Labels    []string
	// LabelColors maps a label to the colour the provider gave it, for the
	// places a label is shown rather than matched on. Empty where a provider
	// has no colours or was not asked for them — a label without one is drawn
	// plain, never dropped.
	LabelColors map[string]string
	Milestone   string
	// The rest is what a provider's own sidebar shows. Anything a provider
	// does not have stays zero rather than being faked.
	Epic      string
	Weight    int
	DueDate   string
	Upvotes   int
	Downvotes int
	Comments  int
	UpdatedAt time.Time
	WebURL    string
	Raw       json.RawMessage
}

type IssueFilter struct {
	State  string // "" means all
	Labels []string
	Search string
	// WithStatus asks for the provider work-item status (GitLab's To do /
	// In progress / Done). It costs an extra request, so only the board —
	// which groups by it — sets it.
	WithStatus bool
}

type Job struct {
	ID           int
	Name         string
	Stage        string
	Status       string
	AllowFailure bool
	Duration     time.Duration
	FinishedAt   time.Time
	WebURL       string
	Raw          json.RawMessage
}

type MRFilter struct {
	State  string
	Labels []string
	Search string
}

type Membership string

type MergeRequest struct {
	ID           int
	Title        string
	Description  string
	State        string // "opened" | "merged" | "closed"
	Author       string
	SourceBranch string
	TargetBranch string
	Draft        bool
	Labels       []string
	Assignees    []string
	Reviewers    []string
	Milestone    string
	Mergeable    bool
	Conflicts    bool
	Upvotes      int
	Downvotes    int
	Comments     int
	UpdatedAt    time.Time
	WebURL       string
	// Refs are the commits the diff is taken against. A review comment has to
	// name them to be positioned, so without them a comment can only be posted
	// unanchored — and a suggestion cannot be posted at all.
	Refs DiffRefs
	Raw  json.RawMessage
}

type Milestone struct {
	ID    int
	Title string
}

type MyWorkFilter struct {
	Kinds []string
	Roles []Role
	State string
}

type Namespace struct {
	ID       int
	FullPath string
	Name     string
	Parent   string
	WebURL   string
}

type Note struct {
	ID     int
	Author string
	// AuthorName is the display name, empty when the provider gives only a
	// login. It is what an avatar takes its initials from.
	AuthorName string
	AvatarURL  string
	Membership Membership
	Body       string
	CreatedAt  time.Time
	// System marks a note the provider generated — "changed the milestone",
	// "added 1 commit" — rather than something a person wrote. These are the
	// history a detail page draws as a timeline.
	System   bool
	Resolved bool
}

type Pipeline struct {
	ID        int
	Status    string
	Ref       string // the branch or tag it ran on
	SHA       string
	Source    string
	WebURL    string
	CreatedAt time.Time
	UpdatedAt time.Time
	Raw       json.RawMessage
}

type PipelineFilter struct {
	Ref    string // only runs on this branch
	Status string
}

type Ref struct {
	Profile   string
	Host      string
	Namespace string // "atomic-blend/backend"
	Project   string // "auth"
}

type Repo struct {
	Ref          Ref
	Name         string
	Description  string
	LastActivity time.Time
	Starred      bool
	WebURL       string
}

type Review struct {
	Verdict  Verdict
	Body     string        // the summary note; may be empty
	Comments []DiffComment // the inline remarks, in reading order
}

type ReviewResult struct{ Unanchored int }

type Role string

type Scope struct {
	Ref   Ref
	Group string
}

type Side string

type Status struct {
	ID   string
	Name string
	// Category buckets the status the way GitLab's own board orders its
	// columns — waiting, running, success or cancelled — derived from the
	// status's icon rather than its name or its always-0 position, which is
	// why internal/ui/board.go sorts the status lanes by this and not by
	// Name. One of the StatusCategory* constants; a provider that answers
	// with something else (or nothing) is treated as StatusCategoryRunning
	// wherever this is read.
	Category string
}

type Suggestion struct {
	// Replacement is the new text, one entry per line, without newlines.
	Replacement []string
	Above       int
	Below       int
	// Note is the reviewer's own words, put above the block.
	Note string
}

type SuggestionStyle int

type Thread struct {
	ID string
	// Resolvable threads are review conversations; a plain comment is not.
	Resolvable bool
	Resolved   bool
	Notes      []Note
}

type TreeEntry struct {
	Name string
	Path string
	Kind string // EntryDir | EntryFile
}

type User struct {
	ID       int
	Username string
	Name     string
}

type Verdict string

type WorkItem struct {
	Ref       Ref
	Kind      string // KindIssue | KindMR
	Role      Role
	ID        int
	Title     string
	State     string
	UpdatedAt time.Time
	WebURL    string
}