package configkit

import (
	"io"

	"go.maximumdirect.net/configkit/internal/engine"
)

// ValueSnapshot describes a saved value as consistently formatted YAML text.
// It is a copy; changing it cannot affect later inspection. Present is false for
// absence or deletion, while explicit null is present. Redacted reports whether
// the value or a descendant was hidden.
type ValueSnapshot struct {
	Present  bool
	Redacted bool
	YAML     string
}

// ValueChange shows values before and after an input contribution or recorded
// application operation, together with its origin, reasons, and dependencies.
type ValueChange struct {
	Before       ValueSnapshot
	After        ValueSnapshot
	Origin       Origin
	Reasons      []string
	Dependencies []Path
}

// SecretReferenceInfo describes a successfully resolved effective reference.
// Name is the environment-variable name, never its value.
type SecretReferenceInfo struct {
	Name string
}

// Explanation describes a path's final value and earlier contributions, with
// sensitive values hidden. It is a copy that cannot alter later inspection.
type Explanation struct {
	Path            Path
	Effective       ValueSnapshot
	Origin          Origin
	History         []ValueChange
	SecretReference *SecretReferenceInfo
}

// Explain returns the saved final value and earlier values for a known current
// or historical path, hiding sensitive information. History follows processing
// order: inheritance appears after source combination and before the transition
// to typed values. Unknown and malformed paths return false.
func (r *Result[T]) Explain(path Path) (Explanation, bool) {
	if r == nil {
		return Explanation{}, false
	}
	value, ok := r.inspection.Explain(toEnginePath(path))
	return fromEngineExplanation(value), ok
}

// WriteEffective writes consistently formatted YAML for the saved final
// configuration, with sensitive values hidden. Later changes to Result.Config
// do not change the output. It is for inspection and is not promised reloadable.
// Writer errors, including short writes, are returned and may leave partial output.
func (r *Result[T]) WriteEffective(output io.Writer) error {
	if r == nil {
		var inspection *engine.Inspection
		return inspection.WriteEffective(output)
	}
	return r.inspection.WriteEffective(output)
}

// WriteExplanation writes a deterministic human-readable rendering of Explain.
// Unknown paths return an error without output. Writer failures may leave partial output.
func (r *Result[T]) WriteExplanation(output io.Writer, path Path) error {
	if r == nil {
		var inspection *engine.Inspection
		return inspection.WriteExplanation(output, toEnginePath(path))
	}
	return r.inspection.WriteExplanation(output, toEnginePath(path))
}