bundler

type BuildCacheEntry struct {
	// Fingerprint is the SHA-256 hash of all build inputs.
	Fingerprint string `json:"fingerprint"`

	// ArtifactName is the name of the built artifact.
	ArtifactName string `json:"artifactName"`

	// ArtifactVersion is the version of the built artifact.
	ArtifactVersion string `json:"artifactVersion"`

	// ArtifactDigest is the OCI digest of the stored artifact.
	ArtifactDigest string `json:"artifactDigest"`

	// CreatedAt is when this cache entry was written.
	CreatedAt time.Time `json:"createdAt"`

	// InputFiles records the number of input files that contributed to the fingerprint.
	InputFiles int `json:"inputFiles"`
}

type BundleFileEntry struct {
	// Path is the file's path relative to the bundle root.
	Path string `json:"path"`
	// Size is the file size in bytes.
	Size int64 `json:"size"`
	// Digest is the SHA-256 content digest.
	Digest string `json:"digest"`
	// Layer is the OCI layer index for this file (version 2 only).
	// In version 1 manifests, this is omitted (all files are in the tar layer).
	Layer int `json:"layer,omitempty"`
}

type BundleManifest struct {
	// Version is the manifest format version.
	Version int `json:"version"`
	// Root is the bundle root directory (always ".").
	Root string `json:"root"`
	// Files lists all bundled files with their paths, sizes, and content digests.
	Files []BundleFileEntry `json:"files"`
	// Plugins lists plugin dependencies (informational, recorded from bundle.plugins).
	Plugins []BundlePluginEntry `json:"plugins,omitempty"`
}

type BundlePluginEntry struct {
	// Name is the plugin's catalog reference.
	Name string `json:"name"`
	// Kind is the plugin type (provider, auth-handler).
	Kind string `json:"kind"`
	// Version is the semver constraint.
	Version string `json:"version"`
}

type CatalogFetcher interface {
	// FetchSolution retrieves a solution by name[@version] and returns
	// the content bytes, the resolved reference info, and any error.
	FetchSolution(ctx context.Context, nameWithVersion string) (content []byte, info catalog.ArtifactInfo, err error)

	// ListSolutions returns all available versions for a named solution artifact.
	// Used for resolving semver constraints to the best matching version.
	ListSolutions(ctx context.Context, name string) ([]catalog.ArtifactInfo, error)
}

type CatalogRefEntry struct {
	// Ref is the original catalog reference (e.g., "deploy-to-k8s@2.0.0").
	Ref string
	// VendorPath is the path within the bundle where the vendored artifact is stored.
	VendorPath string
}

type ComposeOption func(*composeConfig)

type DedupeFileBlob struct {
	// RelPath is the file path relative to the bundle root.
	RelPath string
	// Content is the file's raw bytes.
	Content []byte
	// Digest is the SHA-256 content digest.
	Digest string
	// Size is the file size in bytes.
	Size int64
	// Layer is the 0-based layer index in the OCI manifest (set after partitioning).
	Layer int
}

type DedupeOption func(*dedupeConfig)

type DedupeResult struct {
	// Manifest is the bundle manifest (version 2).
	Manifest *BundleManifest
	// ManifestJSON is the serialized manifest.
	ManifestJSON []byte
	// LargeBlobs are individual file blobs stored as separate OCI layers.
	LargeBlobs []DedupeFileBlob
	// SmallBlobsTar is a tar archive of files below the dedup threshold.
	// May be nil if there are no small files.
	SmallBlobsTar []byte
	// TotalSize is the sum of all file sizes.
	TotalSize int64
}

type DiffResult struct {
	RefA     string        `json:"refA" yaml:"refA"`
	RefB     string        `json:"refB" yaml:"refB"`
	Solution *SolutionDiff `json:"solution,omitempty" yaml:"solution,omitempty"`
	Files    *FilesDiff    `json:"files,omitempty" yaml:"files,omitempty"`
	Vendored *VendoredDiff `json:"vendoredDependencies,omitempty" yaml:"vendoredDependencies,omitempty"`
	Plugins  *PluginsDiff  `json:"plugins,omitempty" yaml:"plugins,omitempty"`
}

type DiffSets struct {
	Added    []string `json:"added,omitempty" yaml:"added,omitempty"`
	Removed  []string `json:"removed,omitempty" yaml:"removed,omitempty"`
	Modified []string `json:"modified,omitempty" yaml:"modified,omitempty"`
}

type DiscoverOption func(*discoverConfig)

type DiscoveryResult struct {
	// LocalFiles are local file paths relative to the bundle root.
	LocalFiles []FileEntry
	// CatalogRefs are catalog references to vendor.
	CatalogRefs []CatalogRefEntry
}

type DiscoverySource int

type DynamicPathWarning struct {
	// Location describes where in the solution the dynamic path was found
	// (e.g., "resolver 'templatePath'").
	Location string
	// Kind is the type of dynamic reference ("expr", "tmpl", "rslvr").
	Kind string
	// Expression is the dynamic expression value.
	Expression string
}

type ExtractedArtifact struct {
	Sol    *solution.Solution
	TmpDir string
}

type FileDiffEntry struct {
	Path string `json:"path" yaml:"path"`
	Size int64  `json:"size,omitempty" yaml:"size,omitempty"`
}

type FileEntry struct {
	// RelPath is the path relative to the bundle root.
	RelPath string
	// Source indicates how the file was discovered.
	Source DiscoverySource
}

type FilesDiff struct {
	Added    []FileDiffEntry `json:"added,omitempty" yaml:"added,omitempty"`
	Removed  []FileDiffEntry `json:"removed,omitempty" yaml:"removed,omitempty"`
	Modified []FileDiffEntry `json:"modified,omitempty" yaml:"modified,omitempty"`
}

type IgnoreChecker interface {
	// IsIgnored returns true if the given relative path should be excluded.
	IsIgnored(relPath string) bool
}

type LocalCatalogFetcherAdapter struct {
	// Catalog is the local catalog instance.
	Catalog *catalog.LocalCatalog
}

type LockDependency struct {
	// Ref is the original catalog reference (e.g., "deploy-to-k8s@2.0.0" or "deploy-to-k8s@^1.5.0").
	Ref string `json:"ref" yaml:"ref" doc:"Original catalog reference" maxLength:"255" example:"deploy-to-k8s@2.0.0"`

	// ResolvedVersion is the exact semver version that was resolved and vendored.
	// For exact refs like "deploy-to-k8s@2.0.0" this equals the version in Ref.
	// For constraint refs like "deploy-to-k8s@^1.5.0" this is the resolved version (e.g., "1.5.2").
	ResolvedVersion string `json:"resolvedVersion,omitempty" yaml:"resolvedVersion,omitempty" doc:"Exact resolved version" maxLength:"50" example:"1.5.2"`

	// Constraint is the original version constraint, if any (e.g., "^1.5.0", ">=2.0.0").
	// Empty for exact version references.
	Constraint string `json:"constraint,omitempty" yaml:"constraint,omitempty" doc:"Original version constraint" maxLength:"100" example:"^1.5.0"`

	// Digest is the SHA-256 content digest of the vendored file.
	Digest string `json:"digest" yaml:"digest" doc:"SHA-256 content digest" maxLength:"128" example:"sha256:abc123..."`

	// ResolvedFrom is the catalog name from which the dependency was fetched.
	ResolvedFrom string `json:"resolvedFrom" yaml:"resolvedFrom" doc:"Source catalog name" maxLength:"255" example:"company-catalog"`

	// VendoredAt is the path relative to the bundle root where the file is stored.
	VendoredAt string `` /* 139-byte string literal not displayed */
}

type LockFile struct {
	// Version is the lock file format version.
	Version int `json:"version" yaml:"version" doc:"Lock file format version" example:"1"`

	// Dependencies lists vendored solution dependencies with their digests.
	Dependencies []LockDependency `json:"dependencies,omitempty" yaml:"dependencies,omitempty" doc:"Vendored solution dependencies" maxItems:"1000"`

	// Plugins lists vendored plugin dependencies with their digests.
	Plugins []LockPlugin `json:"plugins,omitempty" yaml:"plugins,omitempty" doc:"Vendored plugin dependencies" maxItems:"100"`
}

type LockPlugin struct {
	// Name is the plugin name.
	Name string `json:"name" yaml:"name" doc:"Plugin name" maxLength:"100" example:"azure-provider"`

	// Kind is the plugin kind (e.g., "provider", "auth-handler").
	Kind string `json:"kind" yaml:"kind" doc:"Plugin kind" maxLength:"50" example:"provider"`

	// Version is the resolved version string.
	Version string `json:"version" yaml:"version" doc:"Resolved version" maxLength:"50" example:"1.2.3"`

	// Digest is the SHA-256 content digest.
	Digest string `json:"digest" yaml:"digest" doc:"SHA-256 content digest" maxLength:"128" example:"sha256:abc123..."`

	// ResolvedFrom is the source registry or catalog.
	ResolvedFrom string `json:"resolvedFrom" yaml:"resolvedFrom" doc:"Source registry or catalog" maxLength:"255" example:"plugins.example.com"`
}

type PluginDiffEntry struct {
	Name        string `json:"name" yaml:"name"`
	VersionFrom string `json:"versionFrom,omitempty" yaml:"versionFrom,omitempty"`
	VersionTo   string `json:"versionTo,omitempty" yaml:"versionTo,omitempty"`
}

type PluginResolver interface {
	// ResolvePlugin resolves a plugin by name and kind, returning its metadata.
	// If version constraint is non-empty, the resolver should pick the best
	// matching version. Returns the artifact info with the resolved version and digest.
	ResolvePlugin(ctx context.Context, name string, kind catalog.ArtifactKind, versionConstraint string) (catalog.ArtifactInfo, error)
}

type PluginsDiff struct {
	Added    []PluginDiffEntry `json:"added,omitempty" yaml:"added,omitempty"`
	Removed  []PluginDiffEntry `json:"removed,omitempty" yaml:"removed,omitempty"`
	Modified []PluginDiffEntry `json:"modified,omitempty" yaml:"modified,omitempty"`
}

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

type SolutionDiff struct {
	Resolvers DiffSets `json:"resolvers,omitempty" yaml:"resolvers,omitempty"`
	Actions   DiffSets `json:"actions,omitempty" yaml:"actions,omitempty"`
}

type TarOption func(*tarConfig)

type UpdateEntry struct {
	// Ref is the original lock file reference (e.g., "deploy-to-k8s@2.0.0").
	Ref string `json:"ref" yaml:"ref" doc:"Original catalog reference" maxLength:"255" example:"deploy-to-k8s@2.0.0"`
	// LockedVersion is the version from the existing lock file.
	LockedVersion string `json:"lockedVersion" yaml:"lockedVersion" doc:"Version from the existing lock file" maxLength:"50" example:"2.0.0"`
	// LockedDigest is the digest from the existing lock file.
	LockedDigest string `json:"lockedDigest" yaml:"lockedDigest" doc:"Digest from the existing lock file" maxLength:"128" example:"sha256:abc123..."`
	// LatestVersion is the latest resolved version from catalog.
	LatestVersion string `json:"latestVersion" yaml:"latestVersion" doc:"Latest resolved version from catalog" maxLength:"50" example:"2.1.0"`
	// LatestDigest is the digest of the latest content.
	LatestDigest string `json:"latestDigest" yaml:"latestDigest" doc:"Digest of the latest content" maxLength:"128" example:"sha256:def456..."`
	// Content is the raw bytes of the latest fetched content.
	Content []byte `json:"-" yaml:"-"`
	// Info is the artifact info from the catalog resolution.
	Info catalog.ArtifactInfo `json:"-" yaml:"-"`
	// NeedsUpdate indicates whether this entry needs updating.
	NeedsUpdate bool `json:"needsUpdate" yaml:"needsUpdate" doc:"Whether this entry needs updating"`
}

type VendorOptions struct {
	// BundleRoot is the root directory of the solution bundle.
	BundleRoot string
	// VendorDir is the directory to store vendored artifacts.
	VendorDir string
	// LockPath is the path to the lock file.
	LockPath string
	// CatalogFetcher fetches artifacts from catalogs by name[@version].
	// If nil, vendoring will fail when catalog refs are discovered.
	CatalogFetcher CatalogFetcher
}

type VendorPluginsOptions struct {
	// PluginResolver resolves plugins from the catalog.
	// If nil, plugin vendoring is skipped.
	PluginResolver PluginResolver
}

type VendorPluginsResult struct {
	// ResolvedPlugins contains the lock entries for resolved plugins.
	ResolvedPlugins []LockPlugin
}

type VendorResult struct {
	// VendoredFiles contains relative paths (from bundle root) to vendored files.
	VendoredFiles []string
	// Lock is the updated lock file content.
	Lock *LockFile
}

type VendorUpdateOptions struct {
	// SolutionPath is the path to the solution YAML file.
	SolutionPath string `json:"solutionPath" yaml:"solutionPath" doc:"Path to the solution YAML file" maxLength:"500" example:"./solution.yaml"`
	// Dependencies restricts the update to only these dependency refs.
	Dependencies []string `json:"dependencies,omitempty" yaml:"dependencies,omitempty" doc:"Filter to these dependency refs" maxItems:"100"`
	// DryRun previews changes without writing.
	DryRun bool `json:"dryRun" yaml:"dryRun" doc:"Preview without writing"`
	// LockOnly updates the lock file without re-vendoring files.
	LockOnly bool `json:"lockOnly" yaml:"lockOnly" doc:"Update lock file only"`
	// PreRelease includes pre-release versions when resolving.
	PreRelease bool `json:"preRelease" yaml:"preRelease" doc:"Include pre-release versions"`
}

type VendorUpdateResult struct {
	// Entries are the resolved update entries for each dependency.
	Entries []UpdateEntry `json:"entries" yaml:"entries" doc:"Resolved update entries" maxItems:"1000"`
	// UpdateCount is the number of entries that need updating.
	UpdateCount int `json:"updateCount" yaml:"updateCount" doc:"Number of entries needing update" example:"3"`
	// Messages collects informational messages produced during the operation.
	Messages []string `json:"messages,omitempty" yaml:"messages,omitempty" doc:"Informational messages" maxItems:"500"`
	// PluginMessages collects plugin status messages.
	PluginMessages []string `json:"pluginMessages,omitempty" yaml:"pluginMessages,omitempty" doc:"Plugin status messages" maxItems:"100"`
}

type VendoredDiff struct {
	Added    []VendoredEntry   `json:"added,omitempty" yaml:"added,omitempty"`
	Removed  []VendoredEntry   `json:"removed,omitempty" yaml:"removed,omitempty"`
	Upgraded []VendoredUpgrade `json:"upgraded,omitempty" yaml:"upgraded,omitempty"`
}

type VendoredEntry struct {
	Name    string `json:"name" yaml:"name"`
	Version string `json:"version,omitempty" yaml:"version,omitempty"`
}

type VendoredUpgrade struct {
	Name string `json:"name" yaml:"name"`
	From string `json:"from" yaml:"from"`
	To   string `json:"to" yaml:"to"`
}

type VerifyError struct {
	// Path is the file or dependency path that failed verification.
	Path string `json:"path" yaml:"path" doc:"File or dependency path" maxLength:"500"`
	// Reason describes why the verification failed.
	Reason string `json:"reason" yaml:"reason" doc:"Failure reason" maxLength:"1000"`
}

type VerifyResult struct {
	// Errors are hard failures — missing files or dependencies.
	Errors []VerifyError `json:"errors,omitempty" yaml:"errors,omitempty" doc:"Hard verification failures" maxItems:"10000"`
	// Warnings are non-fatal issues (e.g., empty glob patterns, missing bundle).
	Warnings []string `json:"warnings,omitempty" yaml:"warnings,omitempty" doc:"Non-fatal verification issues" maxItems:"10000"`
	// Successes are items that passed verification.
	Successes []string `json:"successes,omitempty" yaml:"successes,omitempty" doc:"Items that passed verification" maxItems:"10000"`
}