forge

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 FieldPatch struct {
	State     *string
	Labels    []string
	Assignees []string
	Milestone *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)
	// 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
}

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
	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 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 Role string

type Side 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 {
	Username string
	Name     string
}

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