component

type AddComponentOptions struct{}

type BuildEnvPreservePolicy string

type ChangedComponentOptions struct {
	ComponentFilter components.ComponentFilter
	// From is the git ref to compare from (e.g., branch, tag, commit hash).
	From string
	// To is the git ref to compare to. Defaults to HEAD.
	To string
	// IncludeUnchanged includes unchanged components in the output.
	IncludeUnchanged bool
}

type ChangedResult struct {
	Component     string `json:"component"`
	ChangeType    string `json:"changeType"`
	SourcesChange bool   `json:"sourcesChange"`
}

type CmdOption func(*cmdOptions)

type ComponentBuildOptions struct {
	ComponentFilter components.ComponentFilter

	ContinueOnError   bool
	NoCheck           bool
	WithoutGitRepo    bool
	RPMDevBumpspec    bool
	SourcePackageOnly bool
	BuildEnvPolicy    BuildEnvPreservePolicy

	LocalRepoPaths           []string
	LocalRepoWithPublishPath string

	// MockConfigOpts is an optional set of key-value config options that will be passed through
	// to mock as --config-opts key=value arguments.
	MockConfigOpts map[string]string
	// contains filtered or unexported fields
}

type ComponentBuildResults struct {
	// Names of the component that was built.
	ComponentName string `json:"componentName"`

	// Absolute paths to any source RPMs built by the operation.
	SRPMPaths []string `json:"srpmPaths" table:"SRPM Paths"`

	// SRPMChannel is the resolved publish channel for the SRPM.
	// Empty when no channel is configured.
	SRPMChannel string `json:"srpmPublishChannel,omitempty" table:"SRPM Publish Channel"`

	// Absolute paths to any RPMs built by the operation.
	RPMPaths []string `json:"rpmPaths" table:"RPM Paths"`

	// RPMChannels holds the resolved publish channel for each RPM, parallel to [RPMPaths].
	// Empty string means no channel was configured for that package.
	RPMChannels []string `json:"rpmChannels" table:"Publish Channels"`

	// RPMs contains enriched per-RPM information including the resolved publish channel.
	RPMs []RPMResult `json:"rpms" table:"-"`
}

type ComponentTestOptions struct {
	ImagePath string
	RPMPaths  []string
	Tests     []string
	WorkDir   string
	Provision string
	// SourceDir points tmt straight at a local fmf tree instead of cloning the
	// catalog 'source' — any directory with an fmf root works, whether produced
	// by 'azldev component render' (with render.skip-file-filter=true) or
	// 'azldev component prepare-sources'.
	SourceDir string
	// Plan overrides 'tmt.plan' from the catalog. Empty means tmt itself
	// discovers and runs every enabled plan it finds, instead of a fixed name
	// (the virtual provisioner is the one exception: it requires an explicit
	// plan, since hardware export is resolved per-plan).
	Plan string
	// FromSpec is deprecated: use SourceDir instead. When set, it resolves to
	// the component's rendered spec directory, preserving the pre-rename
	// '--from-spec' behavior for existing invocations.
	FromSpec bool
}

type CustomizationItem struct {
	Kind        string `json:"kind"`
	Value       string `json:"value,omitempty"`
	Description string `json:"description,omitempty"`
}

type DiffSourcesOptions struct {
	ComponentFilter components.ComponentFilter

	OutputFile string
	// contains filtered or unexported fields
}

type FingerprintChange struct {
	Hash           string `json:"hash"`
	Author         string `json:"author"`
	AuthorEmail    string `json:"authorEmail"`
	Timestamp      int64  `json:"timestamp"`
	Message        string `json:"message"`
	UpstreamCommit string `json:"upstreamCommit,omitempty"`
}

type HistoryOptions struct {
	ComponentFilter components.ComponentFilter
	// SharedTomlMode controls how toml-commit counts are reported for
	// components that share their source TOML file with at least one other
	// component:
	//   "show" (default): include the row, report the count, set SharedToml=true
	//   "omit":           drop the row entirely
	//
	// JSON consumers always see the raw TomlCommits + SharedToml fields and
	// can apply their own presentation (e.g., zero out shared rows) via jq.
	SharedTomlMode string
	// IncludeBare, when true, keeps components with zero customizations in
	// the output. By default they are filtered out -- they have no
	// per-component config worth reporting, and computing their git
	// metrics across all selected components is the dominant cost on
	// large projects (e.g., azurelinux).
	IncludeBare bool
}

type HistoryResult struct {
	// Name of the component. We intentionally do *not* tag this with
	// 'sortkey' -- the reflectable table writer would otherwise re-sort
	// by name and stomp our customizations-first sort.
	Name string `json:"name"`

	// TomlCommits is the number of commits touching the component's source
	// TOML file. When shared-mode = "omit" and the component shares its TOML
	// with another component, the count is suppressed to zero (with
	// SharedToml=true) -- unless the component was named explicitly, which
	// always reports the real count.
	TomlCommits int `json:"tomlCommits"`

	// SharedToml is true when at least one other component anywhere in the
	// project (not just within the current selection) uses the same source
	// TOML file. The TomlCommits count is then coarse because git history
	// is on a per-file basis -- the count includes commits that touched the
	// shared file for any reason, not just for this component.
	SharedToml bool `json:"sharedToml,omitempty"`

	// TomlPath is the repo-relative path of the component's source TOML file.
	TomlPath string `json:"tomlPath,omitempty"`

	// LatestCommit is the timestamp of the most recent commit to the TOML
	// file. Zero if no commits found. Uses 'omitzero' (Go 1.24+) rather than
	// 'omitempty' because the latter is a no-op for struct types and would
	// serialize as "0001-01-01T00:00:00Z" for components with no history.
	LatestCommit time.Time `json:"latestCommit,omitzero" table:"-"`

	// Customizations is the count of customization items (len of the
	// Customization slice).
	Customizations int `json:"customizations"`

	// CustomizationItems are the individual customization records;
	// rendered as JSON detail and as inline expansion for single-component
	// invocations.
	CustomizationItems []CustomizationItem `json:"customizationItems,omitempty" table:"-"`

	// FingerprintChanges is the number of commits where the lock file's
	// input-fingerprint actually changed.
	FingerprintChanges int `json:"fingerprintChanges"`

	// FingerprintChangeDetails is the per-commit metadata for each
	// fingerprint change counted in [FingerprintChanges] (oldest first).
	// Hidden from the human-readable table -- use JSON output to consume
	// them (e.g., to hand-author changelog entries).
	//
	// Each entry is populated from [sources.FingerprintChange] via an
	// explicit field-by-field copy in [populateLockMetrics]. The
	// gathering algorithm is shared with the synthetic dist-git history
	// flow; the wire-level type is local so that:
	//   - the JSON contract for this command lives in this file, and
	//   - removing a field from [sources.FingerprintChange] /
	//     [sources.CommitMetadata] surfaces as a compile error at the
	//     copy site rather than silently dropping changelog metadata.
	// The compile-error guard is one-directional (it catches REMOVED
	// upstream fields); a NEWLY ADDED upstream field is caught instead by
	// TestFingerprintChangeDTOMirrorsSource.
	FingerprintChangeDetails []FingerprintChange `json:"fingerprintChangeDetails,omitempty" table:"-"`

	// HasLock is true when a lock file currently exists for this component.
	HasLock bool `json:"hasLock,omitempty" table:"-"`

	// HasImport is true when the lock file records a non-empty
	// import-commit (i.e., the component was forked from upstream).
	HasImport bool `json:"hasImport,omitempty" table:"-"`

	// ManualBump is the lock file's manual-bump counter. Always emitted
	// (no omitempty) so a real bump of 0 isn't indistinguishable from an
	// absent field; pair it with HasLock to tell "no lock" from "bump 0".
	ManualBump int `json:"manualBump" table:"-"`

	// Warnings collects per-component diagnostics for failure paths that
	// were swallowed to keep the overall report rendering. Empty when no
	// problems were encountered. Surfaces in the single-component card
	// view and in JSON; hidden from the human-readable table.
	Warnings []string `json:"warnings,omitempty" table:"-"`
}

type ListComponentOptions struct {
	// Standard filter for selecting components.
	ComponentFilter components.ComponentFilter
}

type MetadataInfo struct {
	// Component is the name of the component the entry relates to. The output is
	// pre-sorted by [sortMetadataInfos] (by component, then overlays before groups, then
	// index/group name); no `sortkey` tag is set so the table writer preserves that order
	// and stays consistent with JSON/CSV output.
	Component string `json:"component"`

	// Source identifies whether the entry describes an overlay or a component group.
	Source MetadataSource `json:"source"`

	// Index is the 1-based position of the overlay within the component's overlay list. It
	// is 0 for group entries.
	Index int `json:"index,omitempty" table:",omitempty"`

	// Group is the name of the component group for group entries. Empty for overlay entries.
	Group string `json:"group,omitempty" table:",omitempty"`

	// Type is the overlay type (e.g. 'spec-set-tag', 'patch-add'). Empty for group entries.
	Type projectconfig.ComponentOverlayType `json:"type,omitempty" table:",omitempty"`

	// Description is the overlay's or group's top-level human-readable description.
	Description string `json:"description,omitempty" table:",omitempty"`

	// Category surfaces [projectconfig.OverlayMetadata.Category] for tabular output without
	// forcing callers to drill into [MetadataInfo.Metadata]. Empty when the entry has no metadata.
	Category projectconfig.OverlayCategory `json:"category,omitempty" table:",omitempty"`

	// UpstreamStatus surfaces [projectconfig.OverlayMetadata.UpstreamStatus] for tabular
	// output without forcing callers to drill into [MetadataInfo.Metadata]. Empty when
	// the entry has no metadata.
	UpstreamStatus projectconfig.OverlayUpstreamStatus `json:"upstreamStatus,omitempty" table:",omitempty"`

	// Metadata is the full metadata for the entry. Nil when it has none.
	Metadata *projectconfig.OverlayMetadata `json:"metadata,omitempty" table:"-"`
}

type MetadataOptions struct {
	// ComponentFilter selects which components to inspect.
	ComponentFilter components.ComponentFilter

	// Overlays selects overlay metadata for output. When both Overlays and Groups are
	// false, both sources are listed.
	Overlays bool

	// Groups selects component-group metadata for output. When both Overlays and Groups
	// are false, both sources are listed.
	Groups bool

	// Category, when non-empty, filters output to entries whose metadata declares this
	// category.
	Category string

	// UpstreamStatus, when non-empty, filters output to entries whose metadata declares
	// this upstream status (one of the [projectconfig.OverlayUpstreamStatus] values).
	UpstreamStatus string
}

type MetadataSource string

type PrepareSourcesOptions struct {
	ComponentFilter components.ComponentFilter

	OutputDir      string
	SkipOverlays   bool
	WithoutGitRepo bool
	RPMDevBumpspec bool
	Force          bool
	AllowNoHashes  bool
	SkipSources    bool
	// contains filtered or unexported fields
}

type QueryComponentsOptions struct {
	// Standard filter for selecting components.
	ComponentFilter components.ComponentFilter

	// Target architecture passed to rpmspec via --target. Defaults to
	// x86_64. Drives ExclusiveArch/ExcludeArch evaluation; specs that
	// exclude the target are emitted with only SpecInfo.Name populated
	// (no Version/Subpackages) rather than as errors.
	Arch qemu.Arch
}

type RPMResult struct {
	// Path is the absolute path to the RPM file in the build output directory.
	Path string `json:"path" table:"Path"`

	// PackageName is the binary package name extracted from the RPM header tag (e.g., "libcurl-devel").
	PackageName string `json:"packageName" table:"Package"`

	// Channel is the resolved publish channel from project config.
	// Empty when no channel is configured for this package.
	Channel string `json:"publishChannel" table:"Publish Channel"`
}

type RefreshUpstreamCommitOptions struct {
	ComponentFilter components.ComponentFilter
	// UpstreamCommitsDir is the project-relative or absolute directory containing
	// generated per-component TOML files.
	UpstreamCommitsDir string
	// CheckOnly resolves upstream commits but does not write TOML files or
	// prune orphans.
	CheckOnly bool
}

type RefreshUpstreamCommitResult struct {
	Component      string `json:"component"                table:",sortkey"`
	UpstreamCommit string `json:"upstreamCommit,omitempty"`
	PreviousCommit string `json:"previousCommit,omitempty" table:"-"`
	Changed        bool   `json:"changed"`
	Removed        bool   `json:"removed,omitempty"        table:",omitempty"`
	Skipped        bool   `json:"skipped,omitempty"`
	SkipReason     string `json:"skipReason,omitempty"     table:",omitempty"`
	Error          string `json:"error,omitempty"          table:",omitempty"`
}

type RenderOptions struct {
	ComponentFilter   components.ComponentFilter
	OutputDir         string
	OutputDirExplicit bool // True when --output-dir was explicitly passed on the CLI.
	FailOnError       bool
	Force             bool
	CleanStale        bool
	CheckOnly         bool
	RPMDevBumpspec    bool
	// contains filtered or unexported fields
}

type RenderResult struct {
	Component string `json:"component"       table:"Component"`
	OutputDir string `json:"outputDir"       table:"Output"`
	Status    string `json:"status"          table:"Status"`
	Error     string `json:"error,omitempty" table:"Error,omitempty"`
	Changed   bool   `json:"changed"         table:"Changed"`
}

type UpdateComponentOptions struct {
	ComponentFilter components.ComponentFilter
	// Bump increments the manual-rebuild counter on matched components'
	// lock files. Used for mass-rebuild scenarios.
	Bump bool
	// CheckOnly runs the full update pipeline (resolve identities,
	// recompute fingerprints) but does not write lock files or prune
	// orphans. Returns a non-nil error when any component would be
	// changed or any lock file would be pruned. Intended for CI gates:
	// `azldev component update -a --check-only` exits 0 when locks are
	// fresh and 1 when something is stale.
	CheckOnly bool
	// ForceRecalculate disables freshness optimizations that skip
	// re-resolution for unchanged components. When set, all components
	// are re-resolved regardless of their freshness status.
	ForceRecalculate bool
}

type UpdateResult struct {
	Component      string `json:"component"                table:",sortkey"`
	UpstreamCommit string `json:"upstreamCommit,omitempty"`
	PreviousCommit string `json:"previousCommit,omitempty" table:"-"`
	// Changed is set by checkLockChanged (commit diff) or saveComponentLocks (fingerprint diff).
	Changed    bool   `json:"changed"`
	Skipped    bool   `json:"skipped,omitempty"`
	SkipReason string `json:"skipReason,omitempty" table:",omitempty"`
	Error      string `json:"error,omitempty"      table:",omitempty"`
	// contains filtered or unexported fields
}