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 ComponentBuildOptions struct {
	ComponentFilter components.ComponentFilter

	ContinueOnError   bool
	NoCheck           bool
	WithoutGitRepo    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
}

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 CustomizationItem struct {
	Kind        string `json:"kind"`
	Value       string `json:"value,omitempty"`
	Description string `json:"description,omitempty"`
}

type DiffSourcesOptions struct {
	ComponentFilter components.ComponentFilter

	OutputFile string
}

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 PrepareSourcesOptions struct {
	ComponentFilter components.ComponentFilter

	OutputDir      string
	SkipOverlays   bool
	WithoutGitRepo bool
	Force          bool
	AllowNoHashes  bool
	SkipSources    bool
}

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

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 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
}

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
}