provider

type Annotation struct {
	Path      string
	StartLine int
	EndLine   int
	Level     AnnotationLevel
	Title     string
	Message   string
}

type AnnotationLevel string

type Annotator interface {
	// Annotate renders the given annotations in the current run. It is
	// best-effort from the caller's perspective: a returned error is logged,
	// never fatal.
	Annotate(annotations []Annotation) error
}

type ApplyOutputOptions struct {
	ExitCode int
	Success  bool
	Outputs  map[string]string
}

type BaseResolution struct {
	// Ref is a git reference (branch/tag). Mutually exclusive with SHA.
	Ref string

	// SHA is a git commit hash. Mutually exclusive with Ref.
	SHA string

	// HeadSHA is the PR head commit SHA for upload correlation with Atmos Pro.
	// Populated for pull_request events from event.pull_request.head.sha.
	// Empty for non-PR events (push, merge_group, etc.).
	HeadSHA string

	// TargetBranch is the PR target branch name (e.g., "main") when known.
	// Used by callers to recover from missing local refs by running a
	// targeted git fetch. Empty when the event has no notion of a target
	// branch (e.g., push events on the default branch).
	TargetBranch string

	// Source describes where the base was resolved from (for logging).
	Source string

	// EventType describes the CI event (e.g., "pull_request", "push").
	EventType string

	// Checkout classifies what commit the workflow actually checked out,
	// relative to the event payload (e.g., "head.sha", "merge-commit",
	// "synthetic-merge", "unknown"). Base-resolution strategies are only
	// correct for specific checkouts, so surfacing the classification in
	// logs makes wrong-base incidents diagnosable from a single line.
	// Empty for events where the distinction does not apply.
	Checkout string
}

type BranchStatus struct {
	// Branch is the branch name.
	Branch string

	// PullRequest is the PR associated with this branch (nil if none).
	PullRequest *PRStatus

	// CommitSHA is the HEAD commit SHA.
	CommitSHA string

	// Checks are the status checks for this branch/commit.
	Checks []*CheckStatus
}

type CacheProvider interface {
	// Cache returns the provider's cache backend.
	Cache() (cache.Backend, error)
}

type CheckRun struct {
	// ID is the unique identifier for this check run.
	ID int64

	// Name is the check run name (e.g., "atmos/plan: plat-ue2-dev/vpc").
	Name string

	// Status is the current state of the check run.
	Status CheckRunState

	// Conclusion is the final conclusion (success, failure, etc.).
	Conclusion string

	// Title is a short title for the check run output.
	Title string

	// Summary is a markdown summary of the check run results.
	Summary string

	// DetailsURL is a link back to the CI run details.
	DetailsURL string

	// StartedAt is when the check run started.
	StartedAt time.Time

	// CompletedAt is when the check run completed.
	CompletedAt time.Time
}

type CheckRunState string

type CheckStatus struct {
	// Name is the check name.
	Name string

	// Status is the check status (e.g., "queued", "in_progress", "completed").
	Status string

	// Conclusion is the check conclusion (e.g., "success", "failure", "neutral").
	Conclusion string

	// DetailsURL is a link to the check details.
	DetailsURL string
}

type CheckStatusState string

type Comment struct {
	// ID is the provider-specific comment ID.
	ID int64

	// URL is the HTML URL of the comment (if known).
	URL string

	// Body is the final body that was written.
	Body string

	// Created indicates whether a new comment was created (true) or an
	// existing one was updated (false).
	Created bool

	// Target is where the comment landed: CommentTargetPR or CommentTargetCommit.
	// The reporter sets it; providers need not.
	Target CommentTarget
}

type CommentBehavior string

type CommentTarget string

type CommitCommenter interface {
	// PostCommitComment posts or upserts a comment on a commit, matching an existing comment
	// by the marker as PostComment does.
	PostCommitComment(ctx context.Context, opts *PostCommitCommentOptions) (*Comment, error)
}

type ConfigValidator interface {
	// ValidateConfig returns an error when the provider's environment is unusable.
	ValidateConfig() error
}

type Context struct {
	// Provider is the name of the CI provider (e.g., "github-actions").
	Provider string

	// RunID is the unique identifier for this CI run.
	RunID string

	// RunNumber is the run number (increments per workflow).
	RunNumber int

	// RunURL links to this CI run's page (e.g. the GitHub Actions run URL). Empty when the provider cannot determine it.
	RunURL string

	// Workflow is the name of the workflow.
	Workflow string

	// Job is the name of the current job.
	Job string

	// Actor is the user or app that triggered the workflow.
	Actor string

	// EventName is the event that triggered the workflow (e.g., "push", "pull_request").
	EventName string

	// ElevatedEvent reports whether the triggering event runs with the base
	// repository's secrets while the workspace may contain untrusted fork
	// content (GitHub's pull_request_target and workflow_run). Providers set
	// this so the provider-agnostic fork-checkout safety gate can refuse to
	// clone fork content under these events without an explicit opt-in.
	// See docs/prd/native-ci/framework/fork-pr-trust-gate.md.
	ElevatedEvent bool

	// Ref is the git ref (e.g., "refs/heads/main").
	Ref string

	// Branch is the branch name (e.g., "main", "feature/foo").
	Branch string

	// SHA is the git commit SHA.
	SHA string

	// Repository is the full repository name (e.g., "owner/repo").
	Repository string

	// RepoOwner is the repository owner.
	RepoOwner string

	// RepoName is the repository name.
	RepoName string

	// ServerURL is the base URL of the SCM host running this CI
	// (e.g., "https://github.com" or a GitHub Enterprise URL).
	// Empty when the provider cannot determine it.
	ServerURL string

	// CloneURL is the URL to clone the current repository, used by
	// `atmos git clone` for CI checkout replacement. Each provider
	// constructs it from its own metadata; empty when the provider
	// cannot determine it.
	CloneURL string

	// PullRequest contains PR info if this is a pull request event.
	PullRequest *PRInfo

	// MergeQueue identifies the review associated with a merge-queue check run.
	// It is separate from PullRequest: the checkout and status target are still
	// the synthetic queue commit, not the pull request's head commit.
	MergeQueue *MergeQueueInfo
}

type CreateCheckRunOptions struct {
	// Owner is the repository owner.
	Owner string

	// Repo is the repository name.
	Repo string

	// SHA is the commit SHA to create the check run on.
	SHA string

	// Name is the check run name (e.g., "atmos/plan: plat-ue2-dev/vpc").
	Name string

	// Status is the initial status (typically "queued" or "in_progress").
	Status CheckRunState

	// Title is a short title for the check run output.
	Title string

	// Summary is a markdown summary of the check run.
	Summary string

	// DetailsURL is a link back to the CI run.
	DetailsURL string

	// ExternalID is an optional external reference ID.
	ExternalID string
}

type DebugModeDetector interface {
	// IsDebugMode reports whether the current run has debug logging enabled
	// at the CI provider level. Callers use this to auto-promote their own
	// log level.
	IsDebugMode() bool
}

type EnvExporter interface {
	// WriteEnv makes key=value visible to subsequent steps.
	WriteEnv(key, value string) error
	// AddPath prepends dir to PATH for subsequent steps.
	AddPath(dir string) error
}

type FileOutputWriter struct {
	OutputPath  string
	SummaryPath string
}

type LabelReader interface {
	Labels(ctx context.Context, run *Context) ([]string, error)
}

type LogGrouper interface {
	// StartLogGroup opens a collapsible log group with the given title.
	StartLogGroup(title string) error

	// EndLogGroup closes the current log group.
	EndLogGroup() error
}

type LogGroupingSuppressor interface {
	// SuppressLogGrouping reports whether log grouping must be disabled for the
	// current run to keep stdout free of CI workflow-command metadata.
	SuppressLogGrouping() bool
}

type MergeQueueInfo struct {
	PullRequestNumber int
	HeadRef           string
}

type NoopOutputWriter struct{}

type OutputBinder interface {
	// BindOutput returns a provider that writes its local renderings to w.
	BindOutput(w io.Writer) Provider
}

type OutputHelpers struct {
	Writer OutputWriter
}

type OutputWriter interface {
	// WriteOutput writes a key-value pair to CI outputs (e.g., $GITHUB_OUTPUT).
	WriteOutput(key, value string) error

	// WriteSummary writes content to the job summary (e.g., $GITHUB_STEP_SUMMARY).
	WriteSummary(content string) error
}

type PRInfo struct {
	// Number is the PR number.
	Number int

	// HeadRef is the source branch.
	HeadRef string

	// BaseRef is the target branch.
	BaseRef string

	// URL is the PR URL.
	URL string

	// Fork reports whether the pull request head lives in a fork of the base repository.
	Fork bool
}

type PRStatus struct {
	// Number is the PR number.
	Number int

	// Title is the PR title.
	Title string

	// Branch is the head branch name.
	Branch string

	// BaseBranch is the target branch name.
	BaseBranch string

	// URL is the PR URL.
	URL string

	// Checks are the status checks for this PR.
	Checks []*CheckStatus

	// AllPassed is true if all checks have passed.
	AllPassed bool
}

type PlanOutputOptions struct {
	HasChanges        bool
	HasAdditions      bool
	AdditionsCount    int
	ChangesCount      int
	HasDestructions   bool
	DestructionsCount int
	ExitCode          int
	ArtifactKey       string
}

type PostCommentOptions struct {
	// Owner is the repository owner (GitHub) or namespace (GitLab).
	Owner string

	// Repo is the repository name.
	Repo string

	// PRNumber is the pull/merge request number.
	PRNumber int

	// Marker is an HTML/Markdown marker string used to find existing comments
	// on repeat runs. It must appear in Body. Typical value:
	//   "<!-- atmos:ci:plan:<component>:<stack> -->".
	Marker string

	// Body is the full comment body (including Marker).
	Body string

	// Behavior controls create/update/upsert semantics. Empty defaults to
	// CommentBehaviorUpsert.
	Behavior CommentBehavior
}

type PostCommitCommentOptions struct {
	// Owner is the repository owner (GitHub) or namespace (GitLab).
	Owner string

	// Repo is the repository name.
	Repo string

	// SHA is the commit the comment is attached to.
	SHA string

	// Marker is the HTML/Markdown marker used to find an existing comment on repeat runs.
	// It must appear in Body.
	Marker string

	// Body is the full comment body (including Marker).
	Body string

	// Behavior controls create/update/upsert semantics. Empty defaults to
	// CommentBehaviorUpsert.
	Behavior CommentBehavior
}

type Provider interface {
	// Name returns the provider name (e.g., "github-actions", "generic").
	Name() string

	// Detect returns true if this provider is active in the current environment.
	Detect() bool

	// Context returns CI metadata (run ID, PR info, etc.).
	Context() (*Context, error)

	// GetStatus returns PR/commit status for the current branch.
	GetStatus(ctx context.Context, opts StatusOptions) (*Status, error)

	// CreateCheckRun creates a new check run on a commit (like Atlantis status checks).
	CreateCheckRun(ctx context.Context, opts *CreateCheckRunOptions) (*CheckRun, error)

	// UpdateCheckRun updates an existing check run.
	UpdateCheckRun(ctx context.Context, opts *UpdateCheckRunOptions) (*CheckRun, error)

	// PostComment posts or upserts a PR/MR comment. Providers that do not
	// support comments should return errUtils.ErrCIOperationNotSupported.
	// Implementations use the marker string to find and update existing
	// comments on repeat runs (upsert); callers embed the marker in Body.
	PostComment(ctx context.Context, opts *PostCommentOptions) (*Comment, error)

	// OutputWriter returns a writer for CI outputs ($GITHUB_OUTPUT, etc.).
	OutputWriter() OutputWriter

	// ResolveBase returns the base commit for affected detection.
	// Returns nil if the provider cannot determine the base.
	ResolveBase() (*BaseResolution, error)
}

type SARIFReport struct {
	Body     []byte
	Category string

	// Path is the file the report was read from, when it came from one. It is informational: providers
	// that render a report locally name it so the user can tell which file was not uploaded.
	Path string

	// SkipReason is set by the reporter when it routes the report to local rendering because a switch
	// is off (for example "ci.results.enabled is off"). Providers that render locally state it instead
	// of claiming no CI provider was detected.
	SkipReason string
}

type SARIFReporter interface {
	// ReportSARIF uploads the SARIF document to the provider's findings store.
	// Best-effort from the caller's perspective; a returned error is logged,
	// never fatal.
	ReportSARIF(ctx context.Context, report SARIFReport) error
}

type SBOMReport struct {
	Filename string
	Format   string
	Content  []byte
}

type SBOMUpload struct {
	Provider string
	Location string
}

type SBOMUploader interface {
	UploadSBOM(ctx context.Context, report SBOMReport) (*SBOMUpload, error)
}

type Status struct {
	// Repository is the full repository name (e.g., "owner/repo").
	Repository string

	// CurrentBranch contains status for the current branch.
	CurrentBranch *BranchStatus

	// CreatedByUser contains PRs created by the authenticated user.
	CreatedByUser []*PRStatus

	// ReviewRequests contains PRs requesting review from the user.
	ReviewRequests []*PRStatus
}

type StatusOptions struct {
	// Owner is the repository owner.
	Owner string

	// Repo is the repository name.
	Repo string

	// Branch is the branch to check (optional, defaults to current branch).
	Branch string

	// SHA is the commit SHA to check (optional, defaults to HEAD).
	SHA string

	// IncludeUserPRs includes PRs created by the authenticated user.
	IncludeUserPRs bool

	// IncludeReviewRequests includes PRs requesting review from the user.
	IncludeReviewRequests bool
}

type UpdateCheckRunOptions struct {
	// Owner is the repository owner.
	Owner string

	// Repo is the repository name.
	Repo string

	// SHA is the commit SHA (used for fallback creation when no prior CreateCheckRun).
	SHA string

	// Name is the check run name (used as correlation key).
	Name string

	// ID is the identifier of the check run being updated, as returned by CreateCheckRun.
	// Providers that address check runs by ID use it; those that correlate by Name ignore it.
	// Zero means unknown.
	ID int64

	// Status is the new status.
	Status CheckRunState

	// Conclusion is the final conclusion (required when status is "completed").
	Conclusion string

	// Title is the output title (distinct from the check run name).
	Title string

	// Summary is an updated markdown summary.
	Summary string

	// DetailsURL is a link back to the CI run.
	DetailsURL string

	// CompletedAt is when the check run completed.
	CompletedAt *time.Time
}

type ValueMasker interface {
	// MaskValue registers value for redaction in the provider's logs.
	MaskValue(value string) error
}