common

type CodeReviewModule interface {
	loader.Module
	NewCodeReviewTool() (CodeReviewTool, error)
}

type CodeReviewTool interface {
	NewRelease(v *version.Version) Release
	PostReviewRequests(ctxs []*ReviewContext, opts map[string]interface{}) error
	PostReviewFollowupMessage() string
}

type ErrReleaseNotFound struct {
	Version *version.Version
}

type IssueTracker interface {

	// ServiceName returns the name of the service this interface represents.
	ServiceName() string

	// CurrentUser returns the issue tracker account details of the current user.
	// The account ID is taken from the global SalsaFlow configuration file.
	CurrentUser() (User, error)

	// StartableStories returns the list of stories that can be started.
	StartableStories() ([]Story, error)

	// ReviewableStories returns the list of stories that can be assigned
	// a commit to be reviewed, i.e. they are being actively developed and
	// the review phase is not over yet.
	ReviewableStories() ([]Story, error)

	// ReviewedStories returns the list of stories that have been reviewed already.
	ReviewedStories() ([]Story, error)

	// ListStoriesByTag returns the stories for the given list of Story-Id tags.
	ListStoriesByTag(tags []string) ([]Story, error)

	// ListStoriesByRelease returns the stories associated with the given release.
	// An empty slice should be returned in case there are no such stories.
	ListStoriesByRelease(v *version.Version) ([]Story, error)

	// NextRelease is a factory method for creating release objects
	// representing the releases that have not been started yet.
	//
	// The current version is the version on the trunk branch,
	// the next version is the next trunk version, i.e. the version that is bumped
	// to the trunk branch once the release branch is created.
	NextRelease(current *version.Version, next *version.Version) NextRelease

	// RunningRelease is a factory method for creating release objects
	// representing the releases that have been started.
	RunningRelease(*version.Version) RunningRelease

	// OpenStory opens the given story in the web browser.
	OpenStory(storyId string) error

	// StoryTagToReadableStoryId parses the Story-Id tag and returns the relevant readable ID.
	StoryTagToReadableStoryId(tag string) (storyId string, err error)
}

type IssueTrackingModule interface {
	loader.Module
	NewIssueTracker() (IssueTracker, error)
}

type NextRelease interface {
	PromptUserToConfirmStart() (bool, error)
	Start() (action.Action, error)
}

type Release interface {
	// Initialise is called during `release start`
	// when a new version string is committed into trunk.
	Initialise() (rollback action.Action, err error)

	// EnsureClosable makes sure the release can be closed.
	// It returns ErrNotClosable as the root cause in case that is not the case.
	EnsureClosable() error

	// Close closes the given release in the code review tool.
	Close() (rollback action.Action, err error)
}

type ReleaseNotes struct {
	Version  *version.Version
	Sections []*ReleaseNotesSection
}

type ReleaseNotesManager interface {

	// PostReleaseNotes post the given release notes.
	PostReleaseNotes(*ReleaseNotes) (action.Action, error)
}

type ReleaseNotesModule interface {
	loader.Module
	NewReleaseNotesManager() (ReleaseNotesManager, error)
}

type ReleaseNotesSection struct {
	StoryType string
	Stories   []Story
}

type ReleaseNotesSections []*ReleaseNotesSection

type ReviewContext struct {
	Commit *git.Commit
	Story  Story
}

type RunningRelease interface {
	Version() *version.Version
	Stories() ([]Story, error)

	// EnsureStageable shall return ErrNotStageable as the root cause
	// in case it is not possible to stage the given release.
	EnsureStageable() error
	Stage() (action.Action, error)

	// EnsureClosable shall return ErrNotClosable as the root cause
	// in case it is not possible to release the given release.
	EnsureClosable() error
	Close() (action.Action, error)
}

type Stories []Story

type Story interface {
	// Id returns the ID of the story.
	Id() string

	// ReadableId returns the human-friendly ID of the story.
	// This ID is used when listing stories to the user.
	ReadableId() string

	// Type returns a string representing the type of the given issue.
	// The values returned depend on the issue tracker.
	Type() string

	// State returns the abstract state the story is in at the moment.
	State() StoryState

	// URL return the URL that can be used to access the story.
	URL() string

	// Tag returns a string that is then used for the Story-Id tag.
	// The tag is supposed to identify the story, but it might be
	// more complicated than just the story ID.
	Tag() string

	// Title returns a short description of the story.
	// It is used to describe stories when listing them to the user.
	Title() string

	// Assignees returns the list of users that are assigned to the story.
	Assignees() []User

	// AddAssignee can be used to add an additional user to the list of assignees.
	AddAssignee(User) error

	// SetAssigness can be used to set the list of assignees,
	// effectively replacing the current list.
	SetAssignees([]User) error

	// Start can be used to start the story in the issue tracker.
	Start() error

	// MarkAsImplemented marks the story as implemented.
	MarkAsImplemented() (action.Action, error)

	// LessThan is being used for sorting stories for output.
	// Stories are printed in the order they are sorted by this function.
	LessThan(Story) bool

	// IssueTracker can be used to get the issue tracker instance
	// that this story is associated with.
	IssueTracker() IssueTracker
}

type StoryState string

type User interface {
	Id() string
}