gitprovider

type BranchRef struct {
	Owner  string
	Repo   string
	Branch string
}

type DiffStats struct {
	Additions    int32
	Deletions    int32
	ChangedFiles int32
}

type Option func(*providerOptions)

type PRRef struct {
	// Owner is the repository owner / project / workspace.
	Owner string
	// Repo is the repository name or slug.
	Repo string
	// Number is the PR number / IID / index.
	Number int
}

type PRState string

type PRStatus struct {
	// Title is the PR's title/subject line.
	Title string
	// State is the PR's lifecycle state.
	State PRState
	// Draft indicates the PR is marked as draft/WIP.
	Draft bool
	// HeadSHA is the SHA of the head commit.
	HeadSHA string
	// HeadBranch is the name of the branch containing the PR changes.
	HeadBranch string
	// DiffStats summarizes additions/deletions/files changed.
	DiffStats DiffStats
	// ChangesRequested is a convenience boolean: true if any
	// reviewer's current state is "changes_requested".
	ChangesRequested bool
	// AuthorLogin is the login/username of the PR author.
	AuthorLogin string
	// AuthorAvatarURL is the avatar URL of the PR author.
	AuthorAvatarURL string
	// BaseBranch is the target branch the PR will merge into.
	BaseBranch string
	// PRNumber is the PR number (e.g. 1347).
	PRNumber int
	// Commits is the number of commits in the PR.
	Commits int32
	// Approved is true when at least one reviewer has approved
	// and no reviewer has outstanding changes requested.
	Approved bool
	// ReviewerCount is the number of distinct reviewers who
	// have left a decisive review (approved, changes_requested,
	// or dismissed).
	ReviewerCount int32
	// FetchedAt is when this status was fetched.
	FetchedAt time.Time
}

type Provider interface {
	// FetchPullRequestStatus retrieves the complete status of a
	// pull request in the minimum number of API calls for this
	// provider.
	FetchPullRequestStatus(ctx context.Context, token string, ref PRRef) (*PRStatus, error)

	// ResolveBranchPullRequest finds the open PR (if any) for
	// the given branch. Returns nil, nil if no open PR exists.
	ResolveBranchPullRequest(ctx context.Context, token string, ref BranchRef) (*PRRef, error)

	// FetchPullRequestDiff returns the raw unified diff for a
	// pull request. This uses the PR's actual base branch (which
	// may differ from the repo default branch, e.g. a PR
	// targeting "staging" instead of "main"), so it matches what
	// the provider shows on the PR's "Files changed" tab.
	// Returns ErrDiffTooLarge if the diff exceeds MaxDiffSize.
	FetchPullRequestDiff(ctx context.Context, token string, ref PRRef) (string, error)

	// FetchBranchDiff returns the diff of a branch compared
	// against the repository's default branch. This is the
	// fallback when no pull request exists yet (e.g. the agent
	// pushed a branch but hasn't opened a PR). Returns
	// ErrDiffTooLarge if the diff exceeds MaxDiffSize.
	FetchBranchDiff(ctx context.Context, token string, ref BranchRef) (string, error)

	// ParseRepositoryOrigin parses a remote origin URL (HTTPS
	// or SSH) into owner and repo components, returning the
	// normalized HTTPS URL. Returns false if the URL does not
	// match this provider.
	ParseRepositoryOrigin(raw string) (owner, repo, normalizedOrigin string, ok bool)

	// ParsePullRequestURL parses a pull request URL into a
	// PRRef. Returns false if the URL does not match this
	// provider.
	ParsePullRequestURL(raw string) (PRRef, bool)

	// NormalizePullRequestURL normalizes a pull request URL,
	// stripping trailing punctuation, query strings, and
	// fragments. Returns empty string if the URL does not
	// match this provider.
	NormalizePullRequestURL(raw string) string

	// BuildBranchURL constructs a URL to view a branch on
	// the provider's web UI.
	BuildBranchURL(owner, repo, branch string) string

	// BuildRepositoryURL constructs a URL to view a repository
	// on the provider's web UI.
	BuildRepositoryURL(owner, repo string) string

	// BuildPullRequestURL constructs a URL to view a pull
	// request on the provider's web UI.
	BuildPullRequestURL(ref PRRef) string
}

type RateLimitError struct {
	RetryAfter time.Time
}