builder

type BuildBundleOptions struct {
	// BundleMaxSize is the maximum total size for bundled files (e.g., "50MB").
	BundleMaxSize string `json:"bundleMaxSize,omitempty" yaml:"bundleMaxSize,omitempty" doc:"Maximum total size for bundled files"`

	// NoVendor skips catalog dependency vendoring.
	NoVendor bool `json:"noVendor,omitempty" yaml:"noVendor,omitempty" doc:"Skip catalog dependency vendoring"`

	// NoCache skips the build cache and forces a full rebuild.
	NoCache bool `json:"noCache,omitempty" yaml:"noCache,omitempty" doc:"Skip build cache and force a full rebuild"`

	// DryRun previews what would be bundled without writing anything.
	DryRun bool `json:"dryRun,omitempty" yaml:"dryRun,omitempty" doc:"Show what would be bundled without storing"`

	// Dedupe enables content-addressable deduplication.
	Dedupe bool `json:"dedupe,omitempty" yaml:"dedupe,omitempty" doc:"Enable content-addressable deduplication"`

	// DedupeThreshold is the minimum file size for individual layer extraction.
	DedupeThreshold string `json:"dedupeThreshold,omitempty" yaml:"dedupeThreshold,omitempty" doc:"Minimum file size for individual layer extraction"`

	// Logger is used for structured logging during the build.
	Logger logr.Logger

	// OfficialProviders is the official provider registry for auto-injecting
	// missing providers into bundle.plugins at build time. When nil, no
	// auto-injection occurs.
	OfficialProviders *official.Registry

	// Strict disables auto-injection of official providers. When true,
	// missing official providers produce a build error.
	Strict bool
}

type BuildResult struct {
	// TarData is the traditional single tar archive (v1).
	TarData []byte

	// Dedup is the content-addressable dedup result (v2).
	Dedup *bundler.DedupeResult

	// CacheHit indicates the build was served from the build cache.
	// When true, the artifact already exists in the catalog and no store is needed.
	CacheHit bool

	// CacheEntry contains the cache metadata when CacheHit is true.
	CacheEntry *bundler.BuildCacheEntry

	// BuildFingerprint is the computed fingerprint for cache write after a successful build.
	BuildFingerprint string

	// BuildCacheDir is the directory where build cache entries are stored.
	BuildCacheDir string

	// InputFileCount is the number of input files that contributed to the fingerprint.
	InputFileCount int

	// ResolvedPlugins holds plugin lock entries from VendorPlugins,
	// to be merged into the lock file during the store step.
	ResolvedPlugins []bundler.LockPlugin

	// Discovery holds the file discovery results (always populated).
	Discovery *bundler.DiscoveryResult

	// Messages collects human-readable progress messages generated during
	// the pipeline. CLI consumers should display these to the user.
	Messages []string
}

type BundleFile struct {
	// Path is the file path relative to the bundle root.
	Path string `json:"path" yaml:"path"`

	// Source indicates how the file was discovered (static-analysis,
	// explicit-include, or test-include).
	Source string `json:"source" yaml:"source"`
}

type BundlePluginRef struct {
	// Name is the plugin's catalog reference.
	Name string `json:"name" yaml:"name"`

	// Kind is the plugin type (provider or auth-handler).
	Kind string `json:"kind" yaml:"kind"`

	// Version is the semver constraint or "latest".
	Version string `json:"version" yaml:"version"`
}

type BundleReport struct {
	// FileCount is the total number of local files in the bundle.
	FileCount int `json:"fileCount" yaml:"fileCount"`

	// Files lists the local files packaged in the bundle.
	Files []BundleFile `json:"files,omitempty" yaml:"files,omitempty"`

	// VendoredRefs lists the catalog dependencies vendored into the bundle.
	VendoredRefs []VendoredRef `json:"vendoredRefs,omitempty" yaml:"vendoredRefs,omitempty"`

	// Plugins lists the external plugin dependencies recorded for the bundle.
	Plugins []BundlePluginRef `json:"plugins,omitempty" yaml:"plugins,omitempty"`
}

type CatalogPluginResolver struct {
	Catalog catalog.Catalog
}

type PackageReport struct {
	// Name is the resolved artifact name.
	Name string `json:"name" yaml:"name"`

	// Version is the resolved semantic version.
	Version string `json:"version" yaml:"version"`

	// Reference is the canonical artifact reference (e.g., "my-solution@1.2.3").
	Reference string `json:"reference" yaml:"reference"`

	// Digest is the content digest of the stored artifact (sha256:...).
	// Omitted from the report for dry-run builds, where nothing is stored.
	Digest string `json:"digest,omitempty" yaml:"digest,omitempty"`

	// Catalog is the path or name of the catalog the artifact was stored in.
	// Omitted from the report for dry-run builds.
	Catalog string `json:"catalog,omitempty" yaml:"catalog,omitempty"`

	// Size is the stored artifact size in bytes.
	// Omitted from the report for dry-run builds.
	Size int64 `json:"size,omitempty" yaml:"size,omitempty"`

	// DryRun is true when the report describes what would be built without
	// storing anything.
	DryRun bool `json:"dryRun" yaml:"dryRun"`

	// CacheHit is true when the artifact was unchanged since the last build
	// and served from the build cache.
	CacheHit bool `json:"cacheHit" yaml:"cacheHit"`

	// Fingerprint is the build fingerprint used for cache lookups.
	Fingerprint string `json:"fingerprint,omitempty" yaml:"fingerprint,omitempty"`

	// InputFileCount is the number of input files that contributed to the
	// build fingerprint.
	InputFileCount int `json:"inputFileCount,omitempty" yaml:"inputFileCount,omitempty"`

	// Bundle summarizes the files and dependencies packaged with the solution.
	// Nil when packaging with --no-bundle (only the solution YAML is stored).
	Bundle *BundleReport `json:"bundle,omitempty" yaml:"bundle,omitempty"`

	// Verification summarizes the built-bundle completeness check.
	// Nil when verification was skipped (--no-verify) or not applicable (dry-run).
	Verification *VerificationReport `json:"verification,omitempty" yaml:"verification,omitempty"`

	// Solution is the fully composed (flattened) solution document. It is
	// populated only when the caller requests it, so the report stays compact
	// by default.
	Solution *solution.Solution `json:"solution,omitempty" yaml:"solution,omitempty"`
}

type PackageReportInput struct {
	// Name is the resolved artifact name.
	Name string

	// Version is the resolved semantic version.
	Version string

	// Solution is the composed (flattened) solution. Required.
	Solution *solution.Solution

	// Build is the bundle build result. Nil when packaging with --no-bundle.
	Build *BuildResult

	// Info is the stored artifact info. Nil for dry-run reports.
	Info *catalog.ArtifactInfo

	// Verify is the built-bundle verification result. Nil when verification
	// was skipped or is not applicable.
	Verify *bundler.VerifyResult

	// CatalogPath is the path or name of the catalog the artifact was stored in.
	CatalogPath string

	// DryRun marks the report as a preview (nothing stored).
	DryRun bool

	// IncludeSolution embeds the composed solution document in the report.
	IncludeSolution bool
}

type PreflightOptions struct {
	// SkipLint skips the lint pre-flight check entirely.
	SkipLint bool `json:"skipLint,omitempty" yaml:"skipLint,omitempty" doc:"Skip lint pre-flight check"`

	// SkipTests skips the functional test pre-flight check entirely.
	SkipTests bool `json:"skipTests,omitempty" yaml:"skipTests,omitempty" doc:"Skip functional test pre-flight check"`

	// IgnorePreflight runs checks but treats errors as warnings instead of blocking.
	IgnorePreflight bool `json:"ignorePreflight,omitempty" yaml:"ignorePreflight,omitempty" doc:"Run checks but treat errors as warnings"`

	// BinaryPath is the CLI executable path used for test execution.
	// When empty, functional test pre-flight checks are skipped.
	BinaryPath string `json:"binaryPath,omitempty" yaml:"binaryPath,omitempty" doc:"Binary path for test execution"`

	// Registry is the provider registry for lint to validate against.
	// When nil, lint skips provider-specific checks.
	Registry *provider.Registry `json:"-" yaml:"-"`

	// Logger is used for structured logging.
	Logger logr.Logger
}

type PreflightResult struct {
	// LintResult contains lint findings. Nil if lint was skipped.
	LintResult *lint.Result `json:"lintResult,omitempty" yaml:"lintResult,omitempty" doc:"Lint findings"`

	// TestsPassed is true if tests passed or were skipped.
	TestsPassed bool `json:"testsPassed" yaml:"testsPassed" doc:"Whether tests passed or were skipped"`

	// Blocked is true if the build should be aborted.
	Blocked bool `json:"blocked" yaml:"blocked" doc:"Whether the build should be aborted"`

	// Messages collects human-readable status lines for display.
	Messages []string `json:"messages,omitempty" yaml:"messages,omitempty" doc:"Human-readable status lines"`
}

type RegistryFetcherAdapter struct {
	Registry *catalog.Registry
}

type StoreOptions struct {
	// Force overwrites an existing version in the catalog.
	Force bool `json:"force,omitempty" yaml:"force,omitempty" doc:"Overwrite existing version"`

	// Source is the origin of the solution (repository URL or file path), stored as org.opencontainers.image.source.
	Source string `json:"source,omitempty" yaml:"source,omitempty" doc:"Source repository URL or file path"`

	// DisplayName is the human-readable name, stored as an OCI annotation.
	DisplayName string `json:"displayName,omitempty" yaml:"displayName,omitempty" doc:"Human-readable display name"`

	// Description is the solution description, stored as an OCI annotation.
	Description string `json:"description,omitempty" yaml:"description,omitempty" doc:"Solution description"`

	// Category classifies the solution, stored as an OCI annotation.
	Category string `json:"category,omitempty" yaml:"category,omitempty" doc:"Solution category"`

	// Tags are searchable keywords, stored as a comma-separated OCI annotation.
	Tags []string `json:"tags,omitempty" yaml:"tags,omitempty" doc:"Searchable tags"`

	// Annotations is a free-form map merged into OCI annotations.
	// Engine-set annotations take precedence over user-supplied ones.
	Annotations map[string]string `json:"annotations,omitempty" yaml:"annotations,omitempty" doc:"User-supplied annotations"`

	// ArtifactCacheDir is the path to the artifact cache directory.
	// When non-empty, the corresponding artifact cache entry is invalidated
	// after a successful store to prevent stale reads on subsequent runs.
	ArtifactCacheDir string `json:"-" yaml:"-" doc:"Artifact cache directory path"`

	// ArtifactCacheTTL is the TTL for the artifact cache.
	// Required when ArtifactCacheDir is set.
	ArtifactCacheTTL time.Duration `json:"-" yaml:"-" doc:"Artifact cache TTL"`

	// DeferBuildCache, when true, skips writing the build-cache entry during the
	// store. The caller is expected to call WriteBuildCacheEntry only after any
	// post-store verification passes, so a failed verification does not leave a
	// build-cache entry that would let a rerun hit a cached broken artifact and
	// exit 0 without re-verifying.
	DeferBuildCache bool `json:"-" yaml:"-" doc:"Skip writing the build cache entry during store"`
}

type StoreResult struct {
	// Info is the catalog artifact info returned after storing.
	Info catalog.ArtifactInfo `json:"info" yaml:"info" doc:"Artifact info from the catalog"`

	// CacheWritten indicates whether a build cache entry was written.
	CacheWritten bool `json:"cacheWritten,omitempty" yaml:"cacheWritten,omitempty" doc:"Whether the build cache entry was written"`
	// contains filtered or unexported fields
}

type VendoredRef struct {
	// Ref is the original catalog reference (e.g., "deploy-to-k8s@2.0.0").
	Ref string `json:"ref" yaml:"ref"`

	// VendorPath is the path within the bundle where the artifact is stored.
	VendorPath string `json:"vendorPath" yaml:"vendorPath"`
}

type VerificationError struct {
	// Path is the file or dependency path that failed verification.
	Path string `json:"path" yaml:"path"`

	// Reason describes why the verification failed.
	Reason string `json:"reason" yaml:"reason"`
}

type VerificationReport struct {
	// Passed is true when the bundle has no completeness errors.
	Passed bool `json:"passed" yaml:"passed"`

	// Errors are hard completeness failures (missing files or dependencies).
	Errors []VerificationError `json:"errors,omitempty" yaml:"errors,omitempty"`

	// Warnings are non-fatal completeness issues.
	Warnings []string `json:"warnings,omitempty" yaml:"warnings,omitempty"`
}