sourceproviders

type ComponentSourceProvider interface {
	Provider
	SourceIdentityProvider

	// GetComponent retrieves the `.spec` for the specified component along with any sidecar
	// files stored along with it, placing the fetched files in the provided directory.
	GetComponent(
		ctx context.Context, component components.Component, destDirPath string,
		opts ...FetchComponentOption,
	) error
}

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

type FetchComponentOption func(*FetchComponentOptions)

type FetchComponentOptions struct {
	// PreserveGitDir, when true, instructs the provider to keep the upstream .git directory
	// in the fetched component sources instead of deleting it. This is required for building
	// synthetic git history from overlay blame metadata.
	PreserveGitDir bool

	// SkipLookaside, when true, skips all lookaside cache downloads during component
	// fetching. Git-tracked files (spec, patches, scripts) are still fetched from the
	// upstream clone. The sources manifest file remains available for validation.
	SkipLookaside bool
}

type FileSourceProvider interface {
	Provider

	// GetFile retrieves a single source file and places it in destDirPath.
	// Implementations must return [ErrNotFound] (or an error wrapping it) when the
	// provider does not handle the given file reference, so the manager can try the
	// next registered provider before falling back to lookaside and configured origins.
	GetFile(
		ctx context.Context,
		component components.Component,
		fileRef projectconfig.SourceFileReference,
		destDirPath string,
	) error
}

type Provider interface{}

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

type ResolvedDistro struct {
	// Ref is the effective distro reference (component override or project default).
	// Contains the snapshot time used for commit selection.
	Ref projectconfig.DistroReference

	// Definition is the resolved distro definition containing base URIs.
	Definition projectconfig.DistroDefinition

	// Version is the resolved distro version definition containing branch info.
	Version projectconfig.DistroVersionDefinition
}

type SourceIdentityProvider interface {
	// ResolveIdentity returns a deterministic identity string for the component's source.
	// Returns an error if the identity cannot be determined (e.g., network failure for upstream sources).
	// Upstream components must return the resolved commit hash from the dist-git provider, local components
	// must return a content hash of the spec directory (must be stable, but exact format and algorithm
	// are up to the provider).
	ResolveIdentity(ctx context.Context, component components.Component) (string, error)
}

type SourceManager interface {
	// FetchFiles fetches the given source files, placing the files in the provided directory.
	FetchFiles(ctx context.Context, component components.Component, destDirPath string) error

	// FetchComponent fetches an entire upstream component, including its `.spec` file and any sidecar files.
	// Optional [FetchComponentOption] values may be passed to control provider behavior (e.g., preserving
	// the upstream .git directory).
	FetchComponent(
		ctx context.Context, component components.Component, destDirPath string,
		opts ...FetchComponentOption,
	) error

	// ResolveSourceIdentity returns a deterministic identity string for the component's source.
	// For local components, this is a content hash of the spec directory.
	// For upstream components, this is the resolved commit hash from the dist-git provider.
	ResolveSourceIdentity(ctx context.Context, component components.Component) (string, error)
}