renderer

type AffectedResourcesSummary struct {
	Total       int `json:"total"`
	WithChanges int `json:"withChanges"`
	Unchanged   int `json:"unchanged"`
	WithErrors  int `json:"withErrors"`
	// FilteredByPolicy counts XRs excluded because of a Manual compositionUpdatePolicy
	// (FilterReasonManualPolicy).
	FilteredByPolicy int `json:"filteredByPolicy,omitempty"`
	// FilteredBySelector counts XRs excluded because their compositionRevisionSelector does not match
	// the diffed composition's labels (FilterReasonRevisionSelectorMismatch). Kept separate from
	// FilteredByPolicy so the breakdown is visible even in default-discovery mode, where individual
	// XR impacts are not surfaced.
	FilteredBySelector int `json:"filteredBySelector,omitempty"`
	// FilteredByDeletion counts XRs excluded because they are being deleted
	// (FilterReasonDeleting). Kept separate from the other filter counters for the same reason:
	// the breakdown stays visible in default-discovery mode.
	FilteredByDeletion int `json:"filteredByDeletion,omitempty"`
}

type ChangeDetail struct {
	Type       string         `json:"type"`
	APIVersion string         `json:"apiVersion"`
	Kind       string         `json:"kind"`
	Name       string         `json:"name"`
	Namespace  string         `json:"namespace,omitempty"`
	Diff       map[string]any `json:"diff"`

	// DryRun is present only when this resource's desired state was not
	// verified against the apiserver. See dt.DryRunInfo for why absence is the
	// success case and what it does not promise for removals.
	DryRun *dt.DryRunInfo `json:"dryRun,omitempty"`
}

type CompDiffOutput struct {
	Compositions []CompositionDiff
	Errors       []dt.OutputError // top-level errors (e.g., XRs that failed impact analysis)
	// Warnings are non-fatal advisories raised during the run. Like the xr command's, they do not
	// affect the exit code and are not attributed to a single composition — they are raised below the
	// point where the owning composition is known. They have already been written to stderr when
	// raised; this field carries them into structured output. The summary of unverified additions is
	// not among them: the renderer derives it from the diffs (see compDryRunWarnings).
	Warnings []dt.OutputWarning
}

type CompDiffRenderer interface {
	// RenderCompDiff renders the complete composition diff output.
	// Top-level and tool errors go to DiffOptions.Stderr and are included in
	// structured output payloads. Per-composition messages (diffs, "no changes",
	// per-composition errors) go to DiffOptions.Stdout as part of the diff narrative.
	RenderCompDiff(output *CompDiffOutput) error
}

type CompactDiffFormatter struct{}

type CompositionDiff struct {
	Name string
	// Error is the per-composition processing error (nil if successful). Its ResourceID is
	// "Composition/<name>".
	Error             *dt.OutputError
	CompositionDiff   *dt.ResourceDiff // the actual composition diff (nil if unchanged)
	AffectedResources AffectedResourcesSummary
	ImpactAnalysis    []XRImpact
	// ImpactAnalysisSkipped records that the affected XRs were deliberately not evaluated, because
	// the composition changed by less than --analyze-on asked to analyse. Distinguishes "we did not
	// look" from "we looked and found no affected XRs", which would otherwise be indistinguishable.
	//
	// It does not mean ImpactAnalysis is empty. Composites excluded by update policy, revision
	// selector or deletion are identified locally, with no render, so they are reported whether or not
	// the analysis ran — in --resource mode as XRStatusFiltered entries here, and always via the
	// AffectedResources filter counters (issue #478). What a skip suppresses is the renders, and
	// therefore any changed/unchanged/errored verdict about the composites that were kept.
	//
	// Why the composites went unevaluated is not recoverable from this field alone — read
	// RevisionImpact.ChangeScope alongside it. A "none" scope means no CompositionRevision is created
	// and so nothing could have changed; anything else means a revision is created and simply was not
	// evaluated.
	ImpactAnalysisSkipped bool
	// MaskedChangesOnly records that the composition differs from the cluster's only in fields
	// excluded from the rendered diff — the user's --ignore-paths, or the renderer's display-only
	// suppressions. CompositionDiff is nil in that case, but the composition did change, so the
	// renderer must not report it as unchanged.
	MaskedChangesOnly bool
	// RevisionImpact is what applying this composition does to CompositionRevisions, independent of
	// whether anything renders differently. Populated whenever the comparison completed, including
	// when the composites were not evaluated; left zero for a composition that failed to process,
	// where nothing about it was established (see RevisionImpact.determined).
	RevisionImpact RevisionImpact
}

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

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

type DiffFormatter interface {
	Format(diffs []diffmatchpatch.Diff, options DiffOptions) string
}

type DiffOptions struct {
	// Stdout is the writer for diff output (defaults to os.Stdout)
	Stdout io.Writer

	// Stderr is the writer for error output (defaults to os.Stderr)
	// Errors are written here following Unix conventions (errors to stderr, output to stdout)
	Stderr io.Writer

	// Format specifies the output format (diff, json, yaml)
	Format OutputFormat

	// UseColors determines whether to colorize the output
	UseColors bool

	// AddPrefix is the prefix for added lines (default "+")
	AddPrefix string

	// DeletePrefix is the prefix for deleted lines (default "-")
	DeletePrefix string

	// ContextPrefix is the prefix for unchanged lines (default " ")
	ContextPrefix string

	// ContextLines is the number of unchanged lines to show before/after changes in compact mode
	ContextLines int

	// ChunkSeparator is the string used to separate chunks in compact mode
	ChunkSeparator string

	// Compact determines whether to show a compact diff
	Compact bool

	// IgnorePaths is a list of paths to ignore when calculating diffs
	// Supports both simple paths (e.g., "metadata.annotations") and
	// map key paths (e.g., "metadata.annotations[key.name/value]")
	IgnorePaths []string

	// ForVerdict marks a comparison whose result answers "did this object change?" rather than
	// producing output a human reads. Such a comparison keeps the display-only fields *in* the
	// objects being compared (see displayOnlyIgnoredPaths in cleanupForDiff), so a difference in one
	// of them registers: a field hidden purely to keep the rendered diff readable must never decide
	// whether a change exists.
	//
	// Callers should also clear IgnorePaths for such a comparison, for the same reason — the user's
	// masks are a display preference too.
	ForVerdict bool

	// MinimizeComposition collapses composition changes to a single marker line
	// per composition, omitting the full YAML diff body. Only consumed by the
	// human-readable composition diff renderer; structured output is unaffected.
	MinimizeComposition bool

	// OutputVersion selects the schema of structured (JSON/YAML) output. Empty means
	// OutputVersionV1. The human-readable diff format ignores it.
	OutputVersion OutputVersion
}

type DiffRenderer interface {
	// RenderDiffs formats and outputs diffs, grouped by input XR.
	// Diff output goes to DiffOptions.Stdout, errors go to DiffOptions.Stderr.
	// The errs parameter contains the union of resource processing errors to
	// include in output (the top-level/global error list).
	//
	// The warnings parameter carries non-fatal advisories for structured output only. Unlike errors,
	// warnings have ALREADY been written to stderr, at the moment they were raised (see
	// diffprocessor.WarningLogger) — emitting them at render time instead would lose any warning
	// raised during a run that fails before rendering, and would report them out of chronological
	// order with the work that produced them. The human renderer therefore ignores this parameter.
	//
	// One kind of warning is instead derived here, from the groups: the summary of added resources
	// that could not be verified against the apiserver (see dryRunWarnings). Deciding what to summarise
	// is a presentation decision, and the DryRunInfo it is built from only exists once the diffs do.
	// Every renderer writes that summary to stderr; a structured one also appends it to warnings[],
	// after the warnings passed in.
	RenderDiffs(groups []dt.XRDiffGroup, errs []dt.OutputError, warnings []dt.OutputWarning) error
}

type DownstreamChanges struct {
	Summary Summary        `json:"summary"`
	Changes []ChangeDetail `json:"changes"`
}

type FilterReason string

type FullDiffFormatter struct{}

type OutputError = dt.OutputError

type OutputFormat string

type OutputVersion string

type RevisionImpact struct {
	// ChangeScope is how much of the composition differs, in the terms Crossplane uses to decide
	// whether a revision is needed: "none", "metadata" or "spec". Crossplane's Composition.Hash()
	// covers labels and annotations as well as spec, so "metadata" still means a revision is created.
	ChangeScope string `json:"changeScope"`
	// CreatesRevision records whether applying this composition produces a new CompositionRevision.
	CreatesRevision bool `json:"createsRevision"`
	// RepointedComposites counts the composites that would adopt that revision and reconcile as a
	// result: those with an Automatic (or defaulted) compositionUpdatePolicy whose
	// compositionRevisionSelector, if any, selects the resulting revision, and which are not being
	// deleted. A Manual-policy composite is never counted — it is pinned by compositionRevisionRef, so
	// --include-manual keeping it for analysis does not make it re-point (issue #479).
	//
	// Note this counts composites that re-point, which is not the same as composites whose rendered
	// output changes; re-pointing alone usually renders identically.
	RepointedComposites int `json:"repointedComposites"`
	// PredictedRevisionName is what that revision would be called: "<composition>-<hash[:7]>", derived
	// from Crossplane's own Composition.Hash(). When CreatesRevision is false it names the existing
	// revision the composites already track, which is the same name by construction — an unchanged
	// composition hashes to the same value.
	//
	// It is what makes a downstream change interpretable: a composed resource whose template reads the
	// revision name shows a diff with no other visible cause, and this is the cause. The composites are
	// rendered with this value seeded onto their compositionRevisionRef, so such a change is detected
	// rather than assumed away.
	//
	// Absent with CreatesRevision true means the name could not be predicted, which happens when the
	// composition differs from the cluster's only by kubectl's last-applied-configuration annotation:
	// its post-apply value is a function of how the user applies rather than of the file, so the hash —
	// and therefore the name — is unknowable. A warning says so, and nothing is seeded in that case, so
	// a revision-observing change would go undetected. Note also that for a composition applied
	// client-side *with* other edits the suffix is predicted from the file as supplied and so may differ
	// from the eventual one; the change is still detected, its predicted value is just imprecise.
	PredictedRevisionName string `json:"predictedRevisionName,omitempty"`
}

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

type StructuredDiffOutput struct {
	// OutputVersion names the schema of this document.
	OutputVersion OutputVersion `json:"outputVersion"`

	// Summary counts exactly what Changes lists: each distinct change once, however many input XRs
	// reach it. Per-input counts are on each Xrs entry; where inputs overlap those can sum to more.
	Summary Summary `json:"summary"`

	// Changes is the flat, ungrouped list of all resource changes across every
	// input XR.
	//
	// Deprecated: use Xrs for per-input-XR grouping. This field is retained for
	// backward compatibility and will be removed in a future major release.
	Changes []ChangeDetail `json:"changes"`

	// Errors is the union of resource-processing errors across all input XRs
	// (the top-level/global error list). Each errored XR also surfaces its
	// error inside its own Xrs entry; this list stays complete for consumers
	// that read errors here.
	Errors []dt.OutputError `json:"errors,omitempty"`

	// Xrs groups changes by the input XR/claim that produced them, one entry
	// per input in input order. This is the recommended view; the flat Changes
	// field above is deprecated.
	Xrs []xrEntryWire `json:"xrs"`

	// Warnings is the list of non-fatal advisories raised during the run — things worth knowing that
	// did not invalidate the diff. Unlike Errors they do NOT affect the exit code, so a consumer
	// gating on failure should read Errors. Warnings are not grouped per input XR because they
	// originate deep in the call stack, below the point where the owning input is known. They are in
	// the order raised, followed by the renderer's summary of unverified additions (see dryRunWarnings).
	Warnings []dt.OutputWarning `json:"warnings,omitempty"`
}

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

type Summary struct {
	Added    int `json:"added"`
	Modified int `json:"modified"`
	Removed  int `json:"removed"`
}

type XRImpact struct {
	corev1.ObjectReference

	Status XRStatus
	// FilterReason explains a Status == XRStatusFiltered outcome; empty otherwise.
	FilterReason FilterReason
	// FilterDetail is an optional human-readable explanation for a filtered outcome (e.g. which
	// selector failed to match which labels), surfaced to help users self-diagnose the exclusion.
	FilterDetail string
	// Error is the structured processing error for an XRStatusError impact (nil otherwise), the same
	// OutputError the command lists in its top-level errors.
	Error *dt.OutputError
	Diffs map[string]*dt.ResourceDiff // downstream diffs (nil if unchanged/error)
}

type XRStatus string