configgraph

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

type CheckRule struct {
	// ConditionValuer produces the boolean result which determines whether
	// the check passes. The result should be of type [cty.Bool] and should
	// be [cty.True] if the condition is satisfied or [cty.False] if it is
	// not.
	//
	// The valuer is also allowed to return an unknown value if it isn't
	// yet possible to decide whether the condition is satisfied. Null
	// values are not allowed and will cause the check to fail with "error"
	// status.
	ConditionValuer exprs.Valuer

	// ErrorMessageValuer returns a string value containing an error message
	// that should be used when the condition is not satified.
	//
	// The result is required to be known and non-null. If this valuer
	// fails to evaluate with error diagnostics then those error diagnostics
	// will be returned along with a generic error message and the check
	// will fail with the "error" status.
	//
	// This valuer is used only when [ConditionValuer] returns [cty.False].
	ErrorMessageValuer exprs.Valuer

	// DeclSourceRange is a source range that the module author would consider
	// to represent the declaration of this check rule, for use in error
	// messages that describe which rule was responsible for detecting a
	// failure.
	DeclSourceRange tfdiags.SourceRange
}

type CompileProviderConfigRef func(ctx context.Context, providerInstAddr addrs.LocalProviderConfig) exprs.Valuer

type InputVariable struct {
	// Addr is the absolute address of this input variable.
	Addr addrs.AbsInputVariableInstance

	// RawValue produces the "raw" value, as chosen by the caller of the
	// module, which has not yet been type-converted or validated.
	RawValue *OnceValuer

	// TargetType and targetDefaults together represent the type conversion
	// and default object attribute value insertions that must be applied
	// to rawValue to produce the final result.
	TargetType     cty.Type
	TargetDefaults *typeexpr.Defaults

	// FinalizeValue is an optional callback which, if provided, is called
	// during [InputVariable.Value] returns to allow
	// language-edition-specific code to apply any final checks or
	// transformations to the value. The provided value has already been
	// subjected to type conversion, but has not yet had the validation
	// rules applied to it. The result of this function is passed to the
	// validation checks.
	//
	// For example, this is used by package tofu2024 to deal with the various
	// arguments in a variable declaration that affect the interpretation of
	// the value, such as marking it as sensitive.
	//
	// The given context has the values needed to support potentially evaluating
	// other expressions inside the callback.
	FinalizeValue func(context.Context, cty.Value) (cty.Value, tfdiags.Diagnostics)

	// Validation rules are user-defined checks that must succeed for the
	// final value to be considered valid for use in downstream expressions.
	//
	// CompileValidationRules takes the value of the variable after
	// type conversion and built-in validation rules have been applied to
	// it, and returns a sequence of compiled [CheckRule] objects that
	// test whether the author's configured conditions have been met
	// for the given value.
	CompileValidationRules func(ctx context.Context, value cty.Value) iter.Seq[*CheckRule]
}

type InstanceSelector interface {
	// InstanceKeyType returns the instance key type that all instances
	// produced by this selector will have.
	//
	// This is separated to allow for static validation of traversals
	// before actually selecting the instances. It also decides
	// between several different possible representations of an empty
	// set of instances.
	InstanceKeyType() addrs.InstanceKeyType

	// Instances returns a sequence of all of the instance keys, which
	// must must be of the same type returned from InstanceKeyType,
	// and the associated repetition data to use when compiling each
	// instance.
	//
	// If the decision about which instance keys to return was based
	// on evaluating expressions or otherwise interacting with cty values
	// then the result includes any marks that were present on the value used
	// to decide which instance keys exist. If there were no marks at all, or
	// the decision was not based on evaluating expressions, then the value
	// is not marked.
	//
	// If the returned diagnostics contains an error then the set of
	// instance keys is ignored but the returned marks will still be
	// retained and used for building a placeholder result.
	Instances(ctx context.Context) (exprs.FromValue[InstancesSeq], tfdiags.Diagnostics)

	// InstancesSourceRange optionally reports a source range for something in
	// the configuration that the author would consider as representing the
	// rule for deciding which instances exist.
	//
	// For example, this could be the source range of the expression
	// associated with a "for_each" argument, if that was what the
	// selector was based on.
	//
	// If there is no single obvious configuration construct to report
	// then prefer to return nil rather than returning something strange.
	InstancesSourceRange() *tfdiags.SourceRange
}

type InstancesSeq = func(yield func(addrs.InstanceKey, instances.RepetitionData) bool)

type LocalValue struct {
	Addr     addrs.AbsLocalValue
	RawValue *OnceValuer
}

type ModuleCall struct {
	Addr      addrs.AbsModuleCall
	DeclRange tfdiags.SourceRange

	// ParentSourceAddr is the source address of the module that contained
	// this module call, which is then used as the base for resolving
	// any relative addresses returned from SourceAddrValuer.
	ParentSourceAddr addrs.ModuleSource

	// InstanceSelector represents a rule for deciding which instances of
	// this resource have been declared.
	InstanceSelector InstanceSelector

	// SourceAddrValuer and VersionConstraintValuer together describe how
	// to select the module to be called.
	//
	// We currently require these to be equal for all instances of the
	// module call because although in principle this new evaluation model
	// could support entirely different declarations in each module, the
	// surface syntax of HCL would make that very hard to use (can't easily
	// set drastically different arguments for each instance) and this
	// also allows us to echo the design for resource instances where we've
	// effectively already baked in what schema we ought to be validating
	// against before we try to evaluate the config body inside
	// [ModuleCallInstance].
	SourceAddrValuer        *OnceValuer
	VersionConstraintValuer *OnceValuer

	// ValidateSourceArguments is a callback function provided by whatever
	// compiled this [ModuleCall] object that checks whether the source
	// arguments are resolvable in the current execution context, so that we
	// can report any problems just once at the call level rather than
	// re-reporting the same problems once for each instance.
	//
	// Depending on what phase we're in this could either try to find a
	// suitable module in a local cache directory or could even try to actually
	// fetch a remote module over the network, and so this function may take
	// a long time to return.
	ValidateSourceArguments func(ctx context.Context, sourceArgs ModuleSourceArguments) tfdiags.Diagnostics

	// CompileCallInstance is a callback function provided by whatever
	// compiled this [ModuleCall] object that knows how to produce a compiled
	// [ModuleCallInstance] object once we know of the instance key and
	// associated repetition data for it.
	//
	// This indirection allows the caller to take into account the same
	// context it had available when it built this [ModuleCall] object, while
	// incorporating the new information about this specific instance.
	//
	// This should only be called with a [ModuleSourceArguments] that was
	// accepted by [ModuleCall.ValidateSourceArguments] without returning any
	// errors.
	CompileCallInstance func(ctx context.Context, sourceArgs ModuleSourceArguments, key addrs.InstanceKey, repData instances.RepetitionData) *ModuleCallInstance
	// contains filtered or unexported fields
}

type ModuleCallInstance struct {
	// ModuleInstanceAddr is the address of the module instance that this
	// call instance is establishing.
	//
	// The difference between an instance of a module call and an instance
	// of a module is a little fussy and pedantic: the call instance is
	// viewed from the perspective of the caller while the module instance
	// is viewed from the perspective of the callee. But outside of package
	// configgraph that is not a distinction we make and so we don't have
	// a separate address type for an "absolute module call instance".
	ModuleInstanceAddr addrs.ModuleInstance

	// Glue is provided by whatever compiled this object to allow us to learn
	// more about the module that is being called.
	Glue ModuleCallInstanceGlue

	// InputsValuer is a valuer for all of the input variable values taken
	// together as a single object. It's structured this way mainly for
	// consistency with how we deal with the objects representing arguments
	// in other blocks, but it also means that a future edition of the
	// language could potentially use different syntax for input variables
	// that allows constructing the entire map dynamically using expression
	// syntax.
	//
	// TODO: This should actually really be map[addrs.InputVariable]*OnceValuer
	// so that each input variable can be resolved independently, since the
	// "package tofu" implementation allows dependencies from a module
	// instance's output values to its own input variables as long as there
	// are no cycles in the dependency chain within the module.
	InputsValuer *OnceValuer

	// ProvidersFromParent is our representation of the weird
	// "side-channel" that allows providers to pass between modules, which
	// is separate from the concept of input variables despite being
	// conceptually similar.
	ProvidersFromParent CompileProviderConfigRef
	// contains filtered or unexported fields
}

type ModuleCallInstanceGlue interface {
	// ValidateInputs determines whether the given value is a valid
	// representation of the inputs to the target module, returning diagnostics
	// describing any problems.
	//
	// TODO: This probably also needs an argument for describing the
	// "sidechannel" provider instances, as would be specified in the "providers"
	// meta-argument in the current language, so the callee can also check
	// those.
	ValidateInputs(ctx context.Context, inputsVal cty.Value) tfdiags.Diagnostics

	// OutputsValue returns the value representing the outputs of this module
	// instance. This is what should be returned as the value of the module
	// instance.
	//
	// Real implementations of this will tend to indirectly depend on the
	// [ModuleCallInstance.InputsValue] method of the module call instance
	// that this glue object belongs to, but exactly what happens between
	// those two is outside of this package's scope of responsibility.
	OutputsValue(ctx context.Context) (cty.Value, tfdiags.Diagnostics)
}

type ModuleInstance struct {
	Addr addrs.ModuleInstance

	// OutputValuers are the valuers for each of the output values declared
	// in the module. The result value of a module instance is an object
	// value with an attribute for each element in this map.
	OutputValuers map[addrs.OutputValue]*OnceValuer

	// callDeclRange is used for module instances that are produced because
	// of a "module" block in a parent module, or by some similar mechanism
	// like a .tftest.hcl "run" block, which can then be used as a source
	// range for the overall object value representing the module instance's
	// results.
	//
	// This is left as nil for module instances that are created implicitly,
	// such as a root module which is being "called" directly from OpenTofu CLI
	// in a command like "tofu plan".
	CallDeclRange *tfdiags.SourceRange
}

type ModuleSourceArguments struct {
	// Source is the already-parsed-and-normalized module source address.
	Source addrs.ModuleSource

	// AllowedVersions describes what subset of the available versions are
	// accepted, if the source type is one that supports version constraints.
	//
	// It's the responsibility of the [ModuleCall] logic to reject attempts
	// to set a version constraint for a source type that doesn't support
	// it, so a [ModuleSourceArguments] object should not be constructed
	// with a nonzero value in this field when [Source] is not of a
	// version-aware source type.
	AllowedVersions versions.Set
}

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

type OutputValue struct {
	// Addr is the absolute address of this output value.
	Addr addrs.AbsOutputValue

	// Preconditions are user-defined checks that must succeed before OpenTofu
	// will evaluate the output value's expression.
	//
	// Unlike some other uses of [CheckRule], output value preconditions don't
	// have any special local symbols in scope and so are precompiled as part of
	// the [OutputValue] they belong to.
	Preconditions []*CheckRule

	// RawValue produces the "raw" value, as chosen by the caller of the
	// module, which has not yet been type-converted or validated.
	RawValue *OnceValuer

	// TargetType and TargetDefaults together represent the type conversion
	// and default object attribute value insertions that must be applied
	// to RawValue to produce the final result.
	TargetType     cty.Type
	TargetDefaults *typeexpr.Defaults

	// If ForceSensitive is true then the final value will be marked as
	// sensitive regardless of whether the associated raw value was sensitive.
	ForceSensitive bool

	// If ForceEphemeral is true then the final value will be marked as
	// ephemeral regardless of whether the associated raw value was ephemeral.
	ForceEphemeral bool
}

type ProviderConfig struct {
	// FIXME: The current form of AbsProviderConfig is weird and not quite
	// right, because the "Abs" prefix is supposed to represent something
	// belonging to an addrs.ModuleInstance while this models addrs.Module
	// instead. We'll probably need to introduce some temporary new types
	// alongside the existing ones for the sake of this experiment, and then
	// have the new ones replace the old ones if we decide to move forward
	// with something like this.
	Addr      addrs.AbsProviderConfigCorrect
	DeclRange tfdiags.SourceRange

	// InstanceSelector represents a rule for deciding which instances of
	// this resource have been declared.
	InstanceSelector InstanceSelector

	// ProviderAddr is the address of the provider that this is a configuration
	// for. This object can produce zero or more instances of this provider.
	ProviderAddr addrs.Provider

	// CompileProviderInstance is a callback function provided by whatever
	// compiled this [Provider] object that knows how to produce a compiled
	// [ProviderInstance] object once we know of the instance key and associated
	// repetition data for it.
	//
	// This indirection allows the caller to take into account the same
	// context it had available when it built this [Provider] object, while
	// incorporating the new information about this specific instance.
	CompileProviderInstance func(ctx context.Context, key addrs.InstanceKey, repData instances.RepetitionData) *ProviderInstance
	// contains filtered or unexported fields
}

type ProviderInstance struct {
	// Addr is the absolute address of this specific provider instance.
	Addr addrs.AbsProviderInstanceCorrect

	// ProviderAddr is the address of the provider this is an instance of.
	ProviderAddr addrs.Provider

	// ConfigValuer produces the object value representing the configuration
	// for this provider instance.
	ConfigValuer *OnceValuer

	// ValidateConfig is a function provided by whatever compiled this object
	// which takes the result of ConfigValuer and potentially returns additional
	// diagnostics typically based on validation logic built in to the provider
	// itself.
	ValidateConfig func(context.Context, cty.Value) tfdiags.Diagnostics
	// contains filtered or unexported fields
}

type Provisioner struct {
	Type      string
	When      configs.ProvisionerWhen
	OnFailure configs.ProvisionerOnFailure

	// Config is the current instance value specific configuration function
	Config func(context.Context, cty.Value) (ProvisionerConfig, tfdiags.Diagnostics)

	// Dependencies of the configuration (excluding the self value)
	Dependencies iter.Seq[*ResourceInstance]
}

type ProvisionerConfig struct {
	Value      cty.Value
	Connection cty.Value
}

type Resource struct {
	// Addr is the absolute address of this resource, used as the basis of
	// the addresses used to track its instances between plan/apply rounds
	// and between the plan and apply phases in a single round.
	//
	// Placeholder addresses (where the IsPlaceholder method returns true) are
	// allowed here, representing that the containing object is actually
	// itself a placeholder for zero or more resources whose existence
	// and addresses we cannot determine yet.
	Addr addrs.AbsResource

	// InstanceSelector represents a rule for deciding which instances of
	// this resource have been declared.
	InstanceSelector InstanceSelector

	// CompileResourceInstance is a callback function provided by whatever
	// compiled this [Resource] object that knows how to produce a compiled
	// [ResourceInstance] object once we know of the instance key and associated
	// repetition data for it.
	//
	// This indirection allows the caller to take into account the same
	// context it had available when it built this [Resource] object, while
	// incorporating the new information about this specific instance.
	CompileResourceInstance func(ctx context.Context, key addrs.InstanceKey, repData instances.RepetitionData) *ResourceInstance

	DestroyProvisioners func(ctx context.Context, addr addrs.ResourceInstance) []Provisioner

	// PreventDestroyValuer is a valuer that returns the module author's
	// direction about if this resource instance can be destroyed.
	//
	// The valuer must return something that can be converted to [cty.Bool].
	PreventDestroyValuer *OnceValuer

	DeclRange tfdiags.SourceRange
	// contains filtered or unexported fields
}

type ResourceInstance struct {
	// Addr is the absolute address of this resource instance, which is used
	// to track the resource instance between plan/apply rounds and between
	// the plan and apply phases in a single round.
	//
	// Placeholder addresses (where the IsPlaceholder method returns true) are
	// allowed here, representing that the containing object is actually
	// itself a placeholder for zero or more resource instances whose existence
	// and addresses we cannot determine yet.
	Addr addrs.AbsResourceInstance

	// Provider is the provider that this resource's type belongs to. This
	// is the provider to use when asking for config validation, etc.
	Provider addrs.Provider

	// ConfigValuer is a valuer for producing the object value representing
	// the configuration for this object. How the final configuration value
	// is chosen is decided by whatever created this object, but most typically
	// it's by the instance-compilation logic in the parent [Resource].
	ConfigValuer *OnceValuer

	// ProviderInstanceValuer is a valuer for producing a value representing
	// the provider instance that this resource instance is associated with.
	//
	// This valuer should return a value of the capsule type produced by passing
	// the address from the Provider field into [ProviderInstanceRefType],
	// or else type mismatch errors will be reported during evaluation.
	ProviderInstanceValuer *OnceValuer

	// CreateProvisioners are the provisioners to run if the resource instance
	// is being created. These are distinct from Destroy provisioners, which
	// are handled in a different code path.
	CreateProvisioners []Provisioner

	// CreateBeforeDestroyValuer is a valuer that returns the module author's
	// direction about what "replace" order is required for this resource
	// instance.
	//
	// The valuer must return something that can be converted to [cty.Bool].
	CreateBeforeDestroyValuer *OnceValuer

	// IgnoreChangesPaths are paths for which the module author requested
	// that we "ignore changes".
	//
	// To "ignore changes" means to disregard what is configured for anything
	// under a matching path in ConfigVal and to instead treat the corresponding
	// value from the prior state as the effective desired state. This is
	// meaningful only when planning in-place updates to an object that is
	// already tracked in the prior state; it should be ignored when planning
	// to create or delete the object associated with a resource instance.
	//
	// Index steps within the path can potentially have unknown keys if the
	// decision about what to ignore is based on a value that won't be known
	// until the apply phase.
	//
	// This is meaningful only for resource modes that support the "update"
	// change action, and so is always empty for other modes.
	IgnoreChangesPaths []cty.Path

	// ReplaceTriggeredBy describes zero ore more attribute prefixes within
	// other resource instances for which the planning engine should force
	// replacement of this resource instance if any value beneath one of
	// the nominated paths has a change already planned for the current
	// plan/apply round.
	//
	// Index steps within the paths and instance keys within the resource
	// instance addresses can both potentially have unknown keys if the
	// decision about what to refer to is based on a value that won't be known
	// until the apply phase.
	//
	// This is meaningful only for resource modes that support the "update"
	// change action, and so is always false for other modes.
	//
	// Any resource instance mentioned in this collection will always also
	// appear in RequiredResourceInstances.
	ReplaceTriggeredBy []ResourceInstanceAttributePath

	// Glue is provided by the system that "compiled" this [ResourceInstance]
	// object to allow calling back into that system to ask further questions
	// that arise dynamically during evaluation but whose results vary based
	// on concerns that our outside this package's scope.
	Glue ResourceInstanceGlue
	// contains filtered or unexported fields
}

type ResourceInstanceAttributePath struct {
	ResourceInstance addrs.AbsResourceInstance
	Path             cty.Path
}

type ResourceInstanceGlue interface {
	// ResultValue returns the results of whatever side-effects are happening
	// for this resource in the current phase, such as getting the "planned new
	// state" of the resource instance during the plan phase, while keeping this
	// package focused only on the general concern of evaluating expressions
	// in the configuration.
	//
	// If this returns error diagnostics then it MUST also return a suitable
	// placeholder unknown value to use when evaluating downstream expressions.
	// If there's not enough information to return anything more precise
	// then returning [cty.DynamicVal] is an acceptable last resort.
	ResultValue(ctx context.Context, configVal cty.Value, providerInst exprs.FromValue[*ProviderInstance], riDeps addrs.Set[addrs.AbsResourceInstance]) (cty.Value, tfdiags.Diagnostics)
}

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