sdk

type ExplainCandidate struct {
	// Strategy is the name of the strategy that produced this candidate.
	Strategy string

	// Version is the semantic version string (e.g. "1.2.0").
	Version string

	// Source is the short SHA of the source commit, or "external".
	Source string

	// ShouldIncrement indicates whether this candidate would be incremented.
	ShouldIncrement bool

	// Steps records the reasoning chain for how the strategy derived this version.
	Steps []string
}

type ExplainResult struct {
	// Candidates lists all candidate base versions evaluated by strategies.
	Candidates []ExplainCandidate

	// SelectedSource is the human-readable name of the winning strategy.
	SelectedSource string

	// IncrementField is the increment applied (e.g. "Minor", "Patch", "None").
	IncrementField string

	// IncrementSteps records the reasoning for the increment decision.
	IncrementSteps []string

	// PreReleaseSteps records the reasoning for pre-release tag resolution.
	PreReleaseSteps []string

	// FinalVersion is the fully-qualified version string.
	FinalVersion string

	// FormattedOutput is the human-readable explain text (same as CLI --explain).
	FormattedOutput string
}

type LocalOptions struct {
	// Path to the git repository. Defaults to "." if empty.
	Path string

	// Branch overrides the target branch. Empty means use HEAD.
	Branch string

	// Commit overrides the branch tip with a specific SHA. Empty means use tip.
	Commit string

	// ConfigPath is the path to a gitsemver/GitVersion YAML config file.
	// If empty, auto-detects GitVersion.yml or go-gitsemver.yml in the repo root.
	ConfigPath string

	// Explain enables explain mode, populating ExplainResult on the returned Result.
	Explain bool
}

type RemoteOptions struct {
	// Owner is the GitHub repository owner (required).
	Owner string

	// Repo is the GitHub repository name (required).
	Repo string

	// Token is a GitHub personal access token or GITHUB_TOKEN.
	Token string

	// AppID is the GitHub App ID for app authentication.
	AppID int64

	// AppKeyPath is the path to a GitHub App private key PEM file.
	AppKeyPath string

	// BaseURL is a custom GitHub API base URL for GitHub Enterprise.
	BaseURL string

	// Ref is the git ref to version: branch, tag, or SHA. Defaults to the
	// repository's default branch.
	Ref string

	// MaxCommits is the hard cap on commit walk depth. Defaults to 1000.
	MaxCommits int

	// Branch overrides the target branch for context resolution.
	Branch string

	// Commit overrides the branch tip with a specific SHA.
	Commit string

	// ConfigPath is a local config file path that overrides remote config.
	ConfigPath string

	// RemoteConfigPath is a path to a config file in the remote repo (e.g.
	// ".github/GitVersion.yml"). When set, this specific file is fetched instead
	// of auto-detecting from known config file names. Ignored when ConfigPath is set.
	RemoteConfigPath string

	// Explain enables explain mode, populating ExplainResult on the returned Result.
	Explain bool
}

type Result struct {
	// Variables contains all 30+ output variables keyed by name.
	// Common keys: SemVer, FullSemVer, MajorMinorPatch, Major, Minor, Patch,
	// PreReleaseTag, PreReleaseNumber, CommitsSinceVersionSource, Sha, ShortSha,
	// BranchName, etc.
	Variables map[string]string

	// ExplainResult contains the full explain output. Nil when Explain is false.
	ExplainResult *ExplainResult
}