package configkit

import (
	"io"

	"gitea.maximumdirect.net/eric/ConfigKit/internal/engine"
)

// ValueSnapshot is a detached, deterministic YAML representation of one value.
// Present distinguishes absence or deletion from an explicit null value.
type ValueSnapshot struct {
	Present  bool
	Redacted bool
	YAML     string
}

// ValueChange describes one explicit definition or audited domain operation.
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 is a detached safe account of one effective or historical path.
type Explanation struct {
	Path            Path
	Effective       ValueSnapshot
	Origin          Origin
	History         []ValueChange
	SecretReference *SecretReferenceInfo
}

// Explain returns safe effective and chronological values for a known final or
// historical path. Structural inheritance appears between source applications
// and typed reconciliation. 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 deterministic redacted YAML from the frozen resolved
// snapshot. The output is intended 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 produce no 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))
}