vendoring

type ArchivedChecker interface {
	// IsArchived reports whether the repository at gitURI (as produced by
	// version.ExtractGitURI) is archived upstream. Implementations must treat sources that
	// don't support archived detection (non-GitHub hosts) as simply "not archived, no error".
	IsArchived(ctx context.Context, gitURI string) (bool, error)
}

type ComponentDirResolver interface {
	ComponentDir(componentType, component string) (string, error)
}

type DefaultComponentDirResolver struct{}

type DiffParams struct {
	// Source is the Git source URL of the component.
	Source string
	// From is the starting ref; defaults to the component's current pinned version.
	From string
	// To is the ending ref; when empty, the latest semver tag is used.
	To string
	// File optionally restricts the diff to a single path.
	File string
	// Lister resolves the latest tag when To is empty; defaults to version.DefaultLister.
	Lister version.RemoteLister
	// Differ performs the clone+diff; defaults to DefaultDiffer.
	Differ GitDiffer
}

type GitDiffer interface {
	Diff(ctx context.Context, gitURI, fromRef, toRef, file string) (string, error)
}

type GoGitDiffer struct{}

type ResolveSourceParams struct {
	// VendorFile is the --file override; empty means "look for ./vendor.yaml".
	VendorFile string
	// Component is the component name to resolve.
	Component string
	// ComponentType defaults to cfg.TerraformComponentType when empty.
	ComponentType string
	// Resolver defaults to DefaultComponentDirResolver{} when nil.
	Resolver ComponentDirResolver
}

type ResolvedSource struct {
	Source *schema.AtmosVendorSource
	// File is the physical manifest that declares Source (a vendor.yaml/import or a
	// component.yaml) — the file version updates are written back to.
	File string
	// FromComponentManifest is true when Source was resolved from a component.yaml fallback
	// rather than a vendor.yaml source.
	FromComponentManifest bool
	// ComponentType is the component type ("terraform", "helmfile", "packer") this source was
	// resolved under, set only alongside FromComponentManifest. A repo-wide sweep
	// (DiscoverAllComponentManifests) can mix types in one run, so this travels with each
	// individual source rather than being assumed from a single CLI --type flag; see
	// SourceUpdateResult.ComponentType, which carries it into an update report.
	ComponentType string
}

type SourceUpdateResult struct {
	File           string
	Component      string
	CurrentVersion string
	LatestVersion  string
	Status         UpdateStatus
	Reason         string // Populated for StatusSkipped and StatusFailed.
	// Archived reports whether the source's upstream Git repository is archived (GitHub sources
	// only; best-effort). This is orthogonal to Status: a component can be both StatusUpToDate
	// and Archived at the same time, so it's a separate field rather than another UpdateStatus
	// value.
	Archived bool
	// ComponentType is the component type ("terraform", "helmfile", "packer") this result was
	// resolved under, populated only for component.yaml-declared sources (ResolvedSource.ComponentType;
	// see updateResolvedSource). Empty for vendor.yaml-declared sources, which don't carry a single
	// type the same way (each source's own Targets can point anywhere). Used by
	// cmd/vendor/update.go's partitionUpdatedResults to group a repo-wide "--pull" batch by type,
	// since a component-manifest sweep (DiscoverAllComponentManifests) can mix types in one report.
	ComponentType string
}

type UpdateParams struct {
	// VendorFiles are the physical manifest files to process (a vendor.yaml plus
	// any imported files). Edits are applied to the file that declares each source.
	VendorFiles []string
	// ExtraSources are additional already-resolved sources to check/update alongside
	// VendorFiles — used by the opt-in --component-manifests sweep to fold in
	// component.yaml-only components. A component name already present in VendorFiles'
	// sources takes precedence (vendor.yaml wins) and its ExtraSources entry, if any, is
	// skipped.
	ExtraSources []*ResolvedSource
	// Component, when set, restricts updates to that component.
	Component string
	// Tags, when set, restricts updates to sources carrying any of these tags.
	Tags []string
	// Type, when set, restricts updates to sources targeting components of this type.
	Type string
	// DryRun reports what would change without writing files.
	DryRun bool
	// Lister lists remote tags; defaults to version.DefaultLister when nil.
	Lister version.RemoteLister
	// VersionSetter, when set, replaces SetComponentVersion for persisting a resolved
	// version. Component-manifest (component.yaml) sources need spec.source.version
	// instead of vendor.yaml's spec.sources[i].version. Defaults to SetComponentVersion.
	VersionSetter func(file, component, version string) error
	// OnProgress, when set, is called immediately before each source that passes the
	// component/tag/type filters is checked against the remote, reporting the source's
	// component name along with its 1-based position and the total number of sources
	// that will be checked. Used to drive a live "Checking <component>..." progress
	// indicator during what is otherwise a sequence of blocking network calls.
	OnProgress func(component string, index, total int)
	// ArchivedChecker checks whether a source's upstream Git repository is archived; defaults
	// to DefaultArchivedChecker when nil. The check is best-effort and non-fatal: an error here
	// never fails the overall update/check for a source, it only leaves Archived false.
	ArchivedChecker ArchivedChecker
}

type UpdateReport struct {
	Results []SourceUpdateResult
}

type UpdateStatus string