promote

type AncestorFunc func(ancestor, descendant string) (bool, error)

type CleanReleasesRequest struct {
	Environment string
	BaseVersion string
	// SHA is the commit the environment pointed at while diverged (the hotfix
	// merge SHA). It is passed to the release lookup as a fallback so a hotfix
	// release whose tag was already deleted by a prior partial run can still be
	// resolved by its target_commitish and removed, rather than leaking.
	SHA string
	// Spec is the resolved tag grammar. It lets the hotfix-tag match parse a
	// custom pre-release token. A zero value is normalized to the historical
	// default by the cleaner, so callers with no custom grammar can omit it.
	Spec taggrammar.Spec
}

type EnvPromotion struct {
	Environment string `json:"environment"`
	SourceEnv   string `json:"source_env"`
	SHA         string `json:"sha"`
	Version     string `json:"version"`
	NeedsDeploy bool   `json:"needs_deploy"`
}

type FinalizeOption func(*Finalizer)

type Finalizer struct {
	// contains filtered or unexported fields
}

type LifecycleCleaner interface {
	// DeleteEnvBranch deletes the integration branch for env within component:
	// env/<component>/<env>, or env/<env> for the default empty component. The
	// component is recovered from the branch the rejoin is cleaning up so a
	// component's branch is deleted in its own namespace and a sibling's branch is
	// never cross-deleted.
	DeleteEnvBranch(component, env string) error
	// CleanHotfixReleases deletes the hotfix tags and release drafts for the
	// rejoining environment's prior base version.
	CleanHotfixReleases(req CleanReleasesRequest) error
}

type Option func(*guardConfig)

type PreflightResult struct {
	// Mode and configuration
	Mode              PromotionMode `json:"mode"`
	Target            string        `json:"target,omitempty"`              // For cascade mode
	Force             bool          `json:"force,omitempty"`               // For default mode
	RollbackOnFailure bool          `json:"rollback_on_failure,omitempty"` // Revert successful deploys if any fails

	// Source/target info
	SourceEnv     string `json:"source_env"`
	TargetEnv     string `json:"target_env"`
	SourceSHA     string `json:"source_sha"`
	SourceVersion string `json:"source_version"`
	// SourceImageDigest is an immutable artifact identifier (e.g. a Docker image
	// content digest) for the source env, threaded alongside the mutable
	// SourceVersion so operators can pin deploys to immutable content. It is
	// sourced from the source env's build state: cascade treats artifact_id as an
	// opaque immutable id, so this is only a real content digest if the operator's
	// build populates artifact_id with one. When the source env has multiple
	// builds, the first build (by sorted build name) with a non-empty artifact_id
	// is used; when none has one, this stays empty and the deploy input is omitted.
	SourceImageDigest string `json:"source_image_digest,omitempty"`

	// Rollback SHA (target env's current SHA before promotion - what we revert to on failure)
	RollbackSHA string `json:"rollback_sha,omitempty"`

	// Changelog comparison point (SHA of first target env before promotion)
	ChangelogBaseSHA string `json:"changelog_base_sha"`

	// Environments to update
	EnvsToUpdate []string `json:"envs_to_update"`
	SkippedEnvs  []string `json:"skipped_envs"`

	// Deploy decisions
	DeploysToRun         []string `json:"deploys_to_run"`          // Local deploys to run
	ExternalDeploysToRun []string `json:"external_deploys_to_run"` // External deploys to run

	// Release info
	IsPrereleaseEnv bool   `json:"is_prerelease_env"`
	IsFinalEnv      bool   `json:"is_final_env"`
	IsCascade       bool   `json:"is_cascade"`
	ReleaseAction   string `json:"release_action"`

	// Full-pass prod deployment (separate from cascade)
	HasProdDeployment bool   `json:"has_prod_deployment"`
	ProdSHA           string `json:"prod_sha"`
	ProdVersion       string `json:"prod_version"`

	// Breaking changes
	HasBreaking       bool   `json:"has_breaking"`
	CanProceed        bool   `json:"can_proceed"`
	BreakingBlockedAt string `json:"breaking_blocked_at,omitempty"` // The transition that was blocked

	// Warnings carries non-fatal advisories surfaced during preflight, for
	// example a forced override of the diverged-env patch-containment guard.
	Warnings []string `json:"warnings,omitempty"`

	// Full promotion result for downstream use
	PromotionResult *PromotionResult `json:"promotion_result"`
}

type Preflighter struct {
	// contains filtered or unexported fields
}

type PreflighterOptions struct {
	Config            *config.CICDFile
	Mode              PromotionMode
	Target            string // For cascade mode (e.g., "dev-to-prod")
	Force             bool   // For default mode
	BaseDir           string
	DeploysFilter     []string // Specific deploys to include (empty = all)
	RollbackOnFailure bool     // Revert successful deploys if any fails
	AllowDowngrade    bool     // Permit promoting an older version onto an env
}

type Promoter struct {
	// contains filtered or unexported fields
}

type PromoterOptions struct {
	ConfigPath string
	DryRun     bool
	Actor      string
	Force      bool // For default mode: continue on failure
	// Component scopes persisted state to the named declared component. Empty
	// selects the single-component path, byte-identical to today.
	Component string
}

type PromotionMode string

type PromotionResult struct {
	Success        bool           `json:"success"`
	Mode           PromotionMode  `json:"mode"`
	Target         string         `json:"target,omitempty"`       // Target for cascade mode (e.g., "dev-to-prod")
	Force          bool           `json:"force,omitempty"`        // Force flag for default mode
	IsCascade      bool           `json:"is_cascade"`             // True for cascade mode
	Promotions     []EnvPromotion `json:"promotions"`             // Successful promotions
	FailedEnvs     []string       `json:"failed_envs,omitempty"`  // Envs that failed (default+force)
	SkippedEnvs    []string       `json:"skipped_envs,omitempty"` // Envs skipped due to no-op
	FinalEnv       string         `json:"final_env,omitempty"`
	ReleaseAction  string         `json:"release_action,omitempty"` // "prerelease", "publish", or ""
	ReleaseData    *ReleaseData   `json:"release_data,omitempty"`
	ProdDeployment *EnvPromotion  `json:"prod_deployment,omitempty"`
	Error          string         `json:"error,omitempty"`
}

type ReleaseData struct {
	SHA        string `json:"sha"`
	RCVersion  string `json:"rc_version"`  // e.g., v1.0.0-rc.0
	SemVersion string `json:"sem_version"` // e.g., v1.0.0
}