addrs: flesh out functionality ready to replace terraform.ResourceAddress

This "kitchen sink" commit is mainly focused on supporting "targets" as
a new sub-category of addresses, for use-case like the -target CLI option,
but also includes some other functionality to get closer to replacing
terraform.ResourceAddress and fill out some missing parts for representing
various other address types that are currently represented as strings
in the "terraform" package.

addrs/input_variable.go

@@ -1,5 +1,9 @@
 package addrs
 
+import (
+	"fmt"
+)
+
 // InputVariable is the address of an input variable.
 type InputVariable struct {
 	referenceable
@@ -9,3 +13,29 @@ type InputVariable struct {
 func (v InputVariable) String() string {
 	return "var." + v.Name
 }
+
+// AbsInputVariableInstance is the address of an input variable within a
+// particular module instance.
+type AbsInputVariableInstance struct {
+	Module   ModuleInstance
+	Variable InputVariable
+}
+
+// InputVariable returns the absolute address of the input variable of the
+// given name inside the receiving module instance.
+func (m ModuleInstance) InputVariable(name string) AbsInputVariableInstance {
+	return AbsInputVariableInstance{
+		Module: m,
+		Variable: InputVariable{
+			Name: name,
+		},
+	}
+}
+
+func (v AbsInputVariableInstance) String() string {
+	if len(v.Module) == 0 {
+		return v.String()
+	}
+
+	return fmt.Sprintf("%s.%s", v.Module.String(), v.Variable.String())
+}

addrs/local_value.go

@@ -1,5 +1,9 @@
 package addrs
 
+import (
+	"fmt"
+)
+
 // LocalValue is the address of a local value.
 type LocalValue struct {
 	referenceable
@@ -9,3 +13,36 @@ type LocalValue struct {
 func (v LocalValue) String() string {
 	return "local." + v.Name
 }
+
+// Absolute converts the receiver into an absolute address within the given
+// module instance.
+func (v LocalValue) Absolute(m ModuleInstance) AbsLocalValue {
+	return AbsLocalValue{
+		Module:     m,
+		LocalValue: v,
+	}
+}
+
+// AbsLocalValue is the absolute address of a local value within a module instance.
+type AbsLocalValue struct {
+	Module     ModuleInstance
+	LocalValue LocalValue
+}
+
+// LocalValue returns the absolute address of a local value of the given
+// name within the receiving module instance.
+func (m ModuleInstance) LocalValue(name string) AbsLocalValue {
+	return AbsLocalValue{
+		Module: m,
+		LocalValue: LocalValue{
+			Name: name,
+		},
+	}
+}
+
+func (v AbsLocalValue) String() string {
+	if len(v.Module) == 0 {
+		return v.LocalValue.String()
+	}
+	return fmt.Sprintf("%s.%s", v.Module.String(), v.LocalValue.String())
+}

addrs/module.go

@@ -23,6 +23,12 @@ type Module []string
 // represented by RootModuleInstance.
 var RootModule Module
 
+// IsRoot returns true if the receiver is the address of the root module,
+// or false otherwise.
+func (m Module) IsRoot() bool {
+	return len(m) == 0
+}
+
 func (m Module) String() string {
 	if len(m) == 0 {
 		return ""

addrs/module_instance.go

@@ -22,6 +22,10 @@ import (
 // creation.
 type ModuleInstance []ModuleInstanceStep
 
+var (
+	_ Targetable = ModuleInstance(nil)
+)
+
 func ParseModuleInstance(traversal hcl.Traversal) (ModuleInstance, tfdiags.Diagnostics) {
 	mi, remain, diags := parseModuleInstancePrefix(traversal)
 	if len(remain) != 0 {
@@ -157,6 +161,24 @@ func parseModuleInstancePrefix(traversal hcl.Traversal) (ModuleInstance, hcl.Tra
 	return mi, retRemain, diags
 }
 
+// UnkeyedInstanceShim is a shim method for converting a Module address to the
+// equivalent ModuleInstance address that assumes that no modules have
+// keyed instances.
+//
+// This is a temporary allowance for the fact that Terraform does not presently
+// support "count" and "for_each" on modules, and thus graph building code that
+// derives graph nodes from configuration must just assume unkeyed modules
+// in order to construct the graph. At a later time when "count" and "for_each"
+// support is added for modules, all callers of this method will need to be
+// reworked to allow for keyed module instances.
+func (m Module) UnkeyedInstanceShim() ModuleInstance {
+	path := make(ModuleInstance, len(m))
+	for i, name := range m {
+		path[i] = ModuleInstanceStep{Name: name}
+	}
+	return path
+}
+
 // ModuleInstanceStep is a single traversal step through the dynamic module
 // tree. It is used only as part of ModuleInstance.
 type ModuleInstanceStep struct {
@@ -168,6 +190,12 @@ type ModuleInstanceStep struct {
 // module, which is also the zero value of ModuleInstance.
 var RootModuleInstance ModuleInstance
 
+// IsRoot returns true if the receiver is the address of the root module instance,
+// or false otherwise.
+func (m ModuleInstance) IsRoot() bool {
+	return len(m) == 0
+}
+
 // Child returns the address of a child module instance of the receiver,
 // identified by the given name and key.
 func (m ModuleInstance) Child(name string, key InstanceKey) ModuleInstance {
@@ -206,3 +234,105 @@ func (m ModuleInstance) String() string {
 	}
 	return buf.String()
 }
+
+// Ancestors returns a slice containing the receiver and all of its ancestor
+// module instances, all the way up to (and including) the root module.
+// The result is ordered by depth, with the root module always first.
+//
+// Since the result always includes the root module, a caller may choose to
+// ignore it by slicing the result with [1:].
+func (m ModuleInstance) Ancestors() []ModuleInstance {
+	ret := make([]ModuleInstance, 0, len(m)+1)
+	for i := 0; i <= len(m); i++ {
+		ret = append(ret, m[:i])
+	}
+	return ret
+}
+
+// Call returns the module call address that corresponds to the given module
+// instance, along with the address of the module instance that contains it.
+//
+// There is no call for the root module, so this method will panic if called
+// on the root module address.
+//
+// A single module call can produce potentially many module instances, so the
+// result discards any instance key that might be present on the last step
+// of the instance. To retain this, use CallInstance instead.
+//
+// In practice, this just turns the last element of the receiver into a
+// ModuleCall and then returns a slice of the receiever that excludes that
+// last part. This is just a convenience for situations where a call address
+// is required, such as when dealing with *Reference and Referencable values.
+func (m ModuleInstance) Call() (ModuleInstance, ModuleCall) {
+	if len(m) == 0 {
+		panic("cannot produce ModuleCall for root module")
+	}
+
+	inst, lastStep := m[:len(m)-1], m[len(m)-1]
+	return inst, ModuleCall{
+		Name: lastStep.Name,
+	}
+}
+
+// CallInstance returns the module call instance address that corresponds to
+// the given module instance, along with the address of the module instance
+// that contains it.
+//
+// There is no call for the root module, so this method will panic if called
+// on the root module address.
+//
+// In practice, this just turns the last element of the receiver into a
+// ModuleCallInstance and then returns a slice of the receiever that excludes
+// that last part. This is just a convenience for situations where a call\
+// address is required, such as when dealing with *Reference and Referencable
+// values.
+func (m ModuleInstance) CallInstance() (ModuleInstance, ModuleCallInstance) {
+	if len(m) == 0 {
+		panic("cannot produce ModuleCallInstance for root module")
+	}
+
+	inst, lastStep := m[:len(m)-1], m[len(m)-1]
+	return inst, ModuleCallInstance{
+		Call: ModuleCall{
+			Name: lastStep.Name,
+		},
+		Key: lastStep.InstanceKey,
+	}
+}
+
+// TargetContains implements Targetable by returning true if the given other
+// address either matches the receiver, is a sub-module-instance of the
+// receiver, or is a targetable absolute address within a module that
+// is contained within the reciever.
+func (m ModuleInstance) TargetContains(other Targetable) bool {
+	switch to := other.(type) {
+
+	case ModuleInstance:
+		if len(to) < len(m) {
+			// Can't be contained if the path is shorter
+			return false
+		}
+		// Other is contained if its steps match for the length of our own path.
+		for i, ourStep := range m {
+			otherStep := to[i]
+			if ourStep != otherStep {
+				return false
+			}
+		}
+		// If we fall out here then the prefixed matched, so it's contained.
+		return true
+
+	case AbsResource:
+		return m.TargetContains(to.Module)
+
+	case AbsResourceInstance:
+		return m.TargetContains(to.Module)
+
+	default:
+		return false
+	}
+}
+
+func (m ModuleInstance) targetableSigil() {
+	// ModuleInstance is targetable
+}

addrs/output_value.go

@@ -0,0 +1,75 @@
+package addrs
+
+import (
+	"fmt"
+)
+
+// OutputValue is the address of an output value, in the context of the module
+// that is defining it.
+//
+// This is related to but separate from ModuleCallOutput, which represents
+// a module output from the perspective of its parent module. Since output
+// values cannot be represented from the module where they are defined,
+// OutputValue is not Referenceable, while ModuleCallOutput is.
+type OutputValue struct {
+	Name string
+}
+
+func (v OutputValue) String() string {
+	return "output." + v.Name
+}
+
+// Absolute converts the receiver into an absolute address within the given
+// module instance.
+func (v OutputValue) Absolute(m ModuleInstance) AbsOutputValue {
+	return AbsOutputValue{
+		Module:      m,
+		OutputValue: v,
+	}
+}
+
+// AbsOutputValue is the absolute address of an output value within a module instance.
+//
+// This represents an output globally within the namespace of a particular
+// configuration. It is related to but separate from ModuleCallOutput, which
+// represents a module output from the perspective of its parent module.
+type AbsOutputValue struct {
+	Module      ModuleInstance
+	OutputValue OutputValue
+}
+
+// OutputValue returns the absolute address of an output value of the given
+// name within the receiving module instance.
+func (m ModuleInstance) OutputValue(name string) AbsOutputValue {
+	return AbsOutputValue{
+		Module: m,
+		OutputValue: OutputValue{
+			Name: name,
+		},
+	}
+}
+
+func (v AbsOutputValue) String() string {
+	if v.Module.IsRoot() {
+		return v.OutputValue.String()
+	}
+	return fmt.Sprintf("%s.%s", v.Module.String(), v.OutputValue.String())
+}
+
+// ModuleCallOutput converts an AbsModuleOutput into a ModuleCallOutput,
+// returning also the module instance that the ModuleCallOutput is relative
+// to.
+//
+// The root module does not have a call, and so this method cannot be used
+// with outputs in the root module, and will panic in that case.
+func (v AbsOutputValue) ModuleCallOutput() (ModuleInstance, ModuleCallOutput) {
+	if v.Module.IsRoot() {
+		panic("ReferenceFromCall used with root module output")
+	}
+
+	caller, call := v.Module.CallInstance()
+	return caller, ModuleCallOutput{
+		Call: call,
+		Name: v.OutputValue.Name,
+	}
+}

addrs/parse_target.go

@@ -0,0 +1,235 @@
+package addrs
+
+import (
+	"fmt"
+
+	"github.com/hashicorp/hcl2/hcl"
+	"github.com/hashicorp/terraform/tfdiags"
+)
+
+// Target describes a targeted address with source location information.
+type Target struct {
+	Subject     Targetable
+	SourceRange tfdiags.SourceRange
+}
+
+// ParseTarget attempts to interpret the given traversal as a targetable
+// address. The given traversal must be absolute, or this function will
+// panic.
+//
+// If no error diagnostics are returned, the returned target includes the
+// address that was extracted and the source range it was extracted from.
+//
+// If error diagnostics are returned then the Target value is invalid and
+// must not be used.
+func ParseTarget(traversal hcl.Traversal) (*Target, tfdiags.Diagnostics) {
+	path, remain, diags := parseModuleInstancePrefix(traversal)
+	if diags.HasErrors() {
+		return nil, diags
+	}
+
+	rng := tfdiags.SourceRangeFromHCL(traversal.SourceRange())
+
+	if len(remain) == 0 {
+		return &Target{
+			Subject:     path,
+			SourceRange: rng,
+		}, diags
+	}
+
+	mode := ManagedResourceMode
+	if remain.RootName() == "data" {
+		mode = DataResourceMode
+		remain = remain[1:]
+	}
+
+	if len(remain) < 2 {
+		diags = diags.Append(&hcl.Diagnostic{
+			Severity: hcl.DiagError,
+			Summary:  "Invalid address",
+			Detail:   "Resource specification must include a resource type and name.",
+			Subject:  remain.SourceRange().Ptr(),
+		})
+		return nil, diags
+	}
+
+	var typeName, name string
+	switch tt := remain[0].(type) {
+	case hcl.TraverseRoot:
+		typeName = tt.Name
+	case hcl.TraverseAttr:
+		typeName = tt.Name
+	default:
+		switch mode {
+		case ManagedResourceMode:
+			diags = diags.Append(&hcl.Diagnostic{
+				Severity: hcl.DiagError,
+				Summary:  "Invalid address",
+				Detail:   "A resource type name is required.",
+				Subject:  remain[0].SourceRange().Ptr(),
+			})
+		case DataResourceMode:
+			diags = diags.Append(&hcl.Diagnostic{
+				Severity: hcl.DiagError,
+				Summary:  "Invalid address",
+				Detail:   "A data source name is required.",
+				Subject:  remain[0].SourceRange().Ptr(),
+			})
+		default:
+			panic("unknown mode")
+		}
+		return nil, diags
+	}
+
+	switch tt := remain[1].(type) {
+	case hcl.TraverseAttr:
+		name = tt.Name
+	default:
+		diags = diags.Append(&hcl.Diagnostic{
+			Severity: hcl.DiagError,
+			Summary:  "Invalid address",
+			Detail:   "A resource name is required.",
+			Subject:  remain[1].SourceRange().Ptr(),
+		})
+		return nil, diags
+	}
+
+	var subject Targetable
+	remain = remain[2:]
+	switch len(remain) {
+	case 0:
+		subject = path.Resource(mode, typeName, name)
+	case 1:
+		if tt, ok := remain[0].(hcl.TraverseIndex); ok {
+			key, err := ParseInstanceKey(tt.Key)
+			if err != nil {
+				diags = diags.Append(&hcl.Diagnostic{
+					Severity: hcl.DiagError,
+					Summary:  "Invalid address",
+					Detail:   fmt.Sprintf("Invalid resource instance key: %s.", err),
+					Subject:  remain[0].SourceRange().Ptr(),
+				})
+				return nil, diags
+			}
+
+			subject = path.ResourceInstance(mode, typeName, name, key)
+		} else {
+			diags = diags.Append(&hcl.Diagnostic{
+				Severity: hcl.DiagError,
+				Summary:  "Invalid address",
+				Detail:   "Resource instance key must be given in square brackets.",
+				Subject:  remain[0].SourceRange().Ptr(),
+			})
+			return nil, diags
+		}
+	default:
+		diags = diags.Append(&hcl.Diagnostic{
+			Severity: hcl.DiagError,
+			Summary:  "Invalid address",
+			Detail:   "Unexpected extra operators after address.",
+			Subject:  remain[1].SourceRange().Ptr(),
+		})
+		return nil, diags
+	}
+
+	return &Target{
+		Subject:     subject,
+		SourceRange: rng,
+	}, diags
+}
+
+// ParseAbsResource attempts to interpret the given traversal as an absolute
+// resource address, using the same syntax as expected by ParseTarget.
+//
+// If no error diagnostics are returned, the returned target includes the
+// address that was extracted and the source range it was extracted from.
+//
+// If error diagnostics are returned then the AbsResource value is invalid and
+// must not be used.
+func ParseAbsResource(traversal hcl.Traversal) (AbsResource, tfdiags.Diagnostics) {
+	addr, diags := ParseTarget(traversal)
+	if diags.HasErrors() {
+		return AbsResource{}, diags
+	}
+
+	switch tt := addr.Subject.(type) {
+
+	case AbsResource:
+		return tt, diags
+
+	case AbsResourceInstance: // Catch likely user error with specialized message
+		// Assume that the last element of the traversal must be the index,
+		// since that's required for a valid resource instance address.
+		indexStep := traversal[len(traversal)-1]
+		diags = diags.Append(&hcl.Diagnostic{
+			Severity: hcl.DiagError,
+			Summary:  "Invalid address",
+			Detail:   "A resource address is required. This instance key identifies a specific resource instance, which is not expected here.",
+			Subject:  indexStep.SourceRange().Ptr(),
+		})
+		return AbsResource{}, diags
+
+	case ModuleInstance: // Catch likely user error with specialized message
+		diags = diags.Append(&hcl.Diagnostic{
+			Severity: hcl.DiagError,
+			Summary:  "Invalid address",
+			Detail:   "A resource address is required here. The module path must be followed by a resource specification.",
+			Subject:  traversal.SourceRange().Ptr(),
+		})
+		return AbsResource{}, diags
+
+	default: // Generic message for other address types
+		diags = diags.Append(&hcl.Diagnostic{
+			Severity: hcl.DiagError,
+			Summary:  "Invalid address",
+			Detail:   "A resource address is required here.",
+			Subject:  traversal.SourceRange().Ptr(),
+		})
+		return AbsResource{}, diags
+
+	}
+}
+
+// ParseAbsResourceInstance attempts to interpret the given traversal as an
+// absolute resource instance address, using the same syntax as expected by
+// ParseTarget.
+//
+// If no error diagnostics are returned, the returned target includes the
+// address that was extracted and the source range it was extracted from.
+//
+// If error diagnostics are returned then the AbsResource value is invalid and
+// must not be used.
+func ParseAbsResourceInstance(traversal hcl.Traversal) (AbsResourceInstance, tfdiags.Diagnostics) {
+	addr, diags := ParseTarget(traversal)
+	if diags.HasErrors() {
+		return AbsResourceInstance{}, diags
+	}
+
+	switch tt := addr.Subject.(type) {
+
+	case AbsResource:
+		return tt.Instance(NoKey), diags
+
+	case AbsResourceInstance:
+		return tt, diags
+
+	case ModuleInstance: // Catch likely user error with specialized message
+		diags = diags.Append(&hcl.Diagnostic{
+			Severity: hcl.DiagError,
+			Summary:  "Invalid address",
+			Detail:   "A resource instance address is required here. The module path must be followed by a resource instance specification.",
+			Subject:  traversal.SourceRange().Ptr(),
+		})
+		return AbsResourceInstance{}, diags
+
+	default: // Generic message for other address types
+		diags = diags.Append(&hcl.Diagnostic{
+			Severity: hcl.DiagError,
+			Summary:  "Invalid address",
+			Detail:   "A resource address is required here.",
+			Subject:  traversal.SourceRange().Ptr(),
+		})
+		return AbsResourceInstance{}, diags
+
+	}
+}

addrs/parse_target_test.go

@@ -0,0 +1,343 @@
+package addrs
+
+import (
+	"testing"
+
+	"github.com/go-test/deep"
+	"github.com/hashicorp/hcl2/hcl"
+	"github.com/hashicorp/hcl2/hcl/hclsyntax"
+	"github.com/hashicorp/terraform/tfdiags"
+)
+
+func TestParseTarget(t *testing.T) {
+	tests := []struct {
+		Input   string
+		Want    *Target
+		WantErr string
+	}{
+		{
+			`module.foo`,
+			&Target{
+				Subject: ModuleInstance{
+					{
+						Name: "foo",
+					},
+				},
+				SourceRange: tfdiags.SourceRange{
+					Start: tfdiags.SourcePos{Line: 1, Column: 1, Byte: 0},
+					End:   tfdiags.SourcePos{Line: 1, Column: 11, Byte: 10},
+				},
+			},
+			``,
+		},
+		{
+			`module.foo[2]`,
+			&Target{
+				Subject: ModuleInstance{
+					{
+						Name:        "foo",
+						InstanceKey: IntKey(2),
+					},
+				},
+				SourceRange: tfdiags.SourceRange{
+					Start: tfdiags.SourcePos{Line: 1, Column: 1, Byte: 0},
+					End:   tfdiags.SourcePos{Line: 1, Column: 14, Byte: 13},
+				},
+			},
+			``,
+		},
+		{
+			`module.foo[2].module.bar`,
+			&Target{
+				Subject: ModuleInstance{
+					{
+						Name:        "foo",
+						InstanceKey: IntKey(2),
+					},
+					{
+						Name: "bar",
+					},
+				},
+				SourceRange: tfdiags.SourceRange{
+					Start: tfdiags.SourcePos{Line: 1, Column: 1, Byte: 0},
+					End:   tfdiags.SourcePos{Line: 1, Column: 25, Byte: 24},
+				},
+			},
+			``,
+		},
+		{
+			`aws_instance.foo`,
+			&Target{
+				Subject: AbsResource{
+					Resource: Resource{
+						Mode: ManagedResourceMode,
+						Type: "aws_instance",
+						Name: "foo",
+					},
+					Module: RootModuleInstance,
+				},
+				SourceRange: tfdiags.SourceRange{
+					Start: tfdiags.SourcePos{Line: 1, Column: 1, Byte: 0},
+					End:   tfdiags.SourcePos{Line: 1, Column: 17, Byte: 16},
+				},
+			},
+			``,
+		},
+		{
+			`aws_instance.foo[1]`,
+			&Target{
+				Subject: AbsResourceInstance{
+					Resource: ResourceInstance{
+						Resource: Resource{
+							Mode: ManagedResourceMode,
+							Type: "aws_instance",
+							Name: "foo",
+						},
+						Key: IntKey(1),
+					},
+					Module: RootModuleInstance,
+				},
+				SourceRange: tfdiags.SourceRange{
+					Start: tfdiags.SourcePos{Line: 1, Column: 1, Byte: 0},
+					End:   tfdiags.SourcePos{Line: 1, Column: 20, Byte: 19},
+				},
+			},
+			``,
+		},
+		{
+			`data.aws_instance.foo`,
+			&Target{
+				Subject: AbsResource{
+					Resource: Resource{
+						Mode: DataResourceMode,
+						Type: "aws_instance",
+						Name: "foo",
+					},
+					Module: RootModuleInstance,
+				},
+				SourceRange: tfdiags.SourceRange{
+					Start: tfdiags.SourcePos{Line: 1, Column: 1, Byte: 0},
+					End:   tfdiags.SourcePos{Line: 1, Column: 22, Byte: 21},
+				},
+			},
+			``,
+		},
+		{
+			`data.aws_instance.foo[1]`,
+			&Target{
+				Subject: AbsResourceInstance{
+					Resource: ResourceInstance{
+						Resource: Resource{
+							Mode: DataResourceMode,
+							Type: "aws_instance",
+							Name: "foo",
+						},
+						Key: IntKey(1),
+					},
+					Module: RootModuleInstance,
+				},
+				SourceRange: tfdiags.SourceRange{
+					Start: tfdiags.SourcePos{Line: 1, Column: 1, Byte: 0},
+					End:   tfdiags.SourcePos{Line: 1, Column: 25, Byte: 24},
+				},
+			},
+			``,
+		},
+		{
+			`module.foo.aws_instance.bar`,
+			&Target{
+				Subject: AbsResource{
+					Resource: Resource{
+						Mode: ManagedResourceMode,
+						Type: "aws_instance",
+						Name: "bar",
+					},
+					Module: ModuleInstance{
+						{Name: "foo"},
+					},
+				},
+				SourceRange: tfdiags.SourceRange{
+					Start: tfdiags.SourcePos{Line: 1, Column: 1, Byte: 0},
+					End:   tfdiags.SourcePos{Line: 1, Column: 28, Byte: 27},
+				},
+			},
+			``,
+		},
+		{
+			`module.foo.module.bar.aws_instance.baz`,
+			&Target{
+				Subject: AbsResource{
+					Resource: Resource{
+						Mode: ManagedResourceMode,
+						Type: "aws_instance",
+						Name: "baz",
+					},
+					Module: ModuleInstance{
+						{Name: "foo"},
+						{Name: "bar"},
+					},
+				},
+				SourceRange: tfdiags.SourceRange{
+					Start: tfdiags.SourcePos{Line: 1, Column: 1, Byte: 0},
+					End:   tfdiags.SourcePos{Line: 1, Column: 39, Byte: 38},
+				},
+			},
+			``,
+		},
+		{
+			`module.foo.module.bar.aws_instance.baz["hello"]`,
+			&Target{
+				Subject: AbsResourceInstance{
+					Resource: ResourceInstance{
+						Resource: Resource{
+							Mode: ManagedResourceMode,
+							Type: "aws_instance",
+							Name: "baz",
+						},
+						Key: StringKey("hello"),
+					},
+					Module: ModuleInstance{
+						{Name: "foo"},
+						{Name: "bar"},
+					},
+				},
+				SourceRange: tfdiags.SourceRange{
+					Start: tfdiags.SourcePos{Line: 1, Column: 1, Byte: 0},
+					End:   tfdiags.SourcePos{Line: 1, Column: 48, Byte: 47},
+				},
+			},
+			``,
+		},
+		{
+			`module.foo.data.aws_instance.bar`,
+			&Target{
+				Subject: AbsResource{
+					Resource: Resource{
+						Mode: DataResourceMode,
+						Type: "aws_instance",
+						Name: "bar",
+					},
+					Module: ModuleInstance{
+						{Name: "foo"},
+					},
+				},
+				SourceRange: tfdiags.SourceRange{
+					Start: tfdiags.SourcePos{Line: 1, Column: 1, Byte: 0},
+					End:   tfdiags.SourcePos{Line: 1, Column: 33, Byte: 32},
+				},
+			},
+			``,
+		},
+		{
+			`module.foo.module.bar.data.aws_instance.baz`,
+			&Target{
+				Subject: AbsResource{
+					Resource: Resource{
+						Mode: DataResourceMode,
+						Type: "aws_instance",
+						Name: "baz",
+					},
+					Module: ModuleInstance{
+						{Name: "foo"},
+						{Name: "bar"},
+					},
+				},
+				SourceRange: tfdiags.SourceRange{
+					Start: tfdiags.SourcePos{Line: 1, Column: 1, Byte: 0},
+					End:   tfdiags.SourcePos{Line: 1, Column: 44, Byte: 43},
+				},
+			},
+			``,
+		},
+		{
+			`module.foo.module.bar.data.aws_instance.baz["hello"]`,
+			&Target{
+				Subject: AbsResourceInstance{
+					Resource: ResourceInstance{
+						Resource: Resource{
+							Mode: DataResourceMode,
+							Type: "aws_instance",
+							Name: "baz",
+						},
+						Key: StringKey("hello"),
+					},
+					Module: ModuleInstance{
+						{Name: "foo"},
+						{Name: "bar"},
+					},
+				},
+				SourceRange: tfdiags.SourceRange{
+					Start: tfdiags.SourcePos{Line: 1, Column: 1, Byte: 0},
+					End:   tfdiags.SourcePos{Line: 1, Column: 53, Byte: 52},
+				},
+			},
+			``,
+		},
+
+		{
+			`aws_instance`,
+			nil,
+			`Resource specification must include a resource type and name.`,
+		},
+		{
+			`module`,
+			nil,
+			`Prefix "module." must be followed by a module name.`,
+		},
+		{
+			`module["baz"]`,
+			nil,
+			`Prefix "module." must be followed by a module name.`,
+		},
+		{
+			`module.baz.bar`,
+			nil,
+			`Resource specification must include a resource type and name.`,
+		},
+		{
+			`aws_instance.foo.bar`,
+			nil,
+			`Resource instance key must be given in square brackets.`,
+		},
+		{
+			`aws_instance.foo[1].baz`,
+			nil,
+			`Unexpected extra operators after address.`,
+		},
+	}
+
+	for _, test := range tests {
+		t.Run(test.Input, func(t *testing.T) {
+			traversal, travDiags := hclsyntax.ParseTraversalAbs([]byte(test.Input), "", hcl.Pos{Line: 1, Column: 1})
+			if travDiags.HasErrors() {
+				t.Fatal(travDiags.Error())
+			}
+
+			got, diags := ParseTarget(traversal)
+
+			switch len(diags) {
+			case 0:
+				if test.WantErr != "" {
+					t.Fatalf("succeeded; want error: %s", test.WantErr)
+				}
+			case 1:
+				if test.WantErr == "" {
+					t.Fatalf("unexpected diagnostics: %s", diags.Err())
+				}
+				if got, want := diags[0].Description().Detail, test.WantErr; got != want {
+					t.Fatalf("wrong error\ngot:  %s\nwant: %s", got, want)
+				}
+			default:
+				t.Fatalf("too many diagnostics: %s", diags.Err())
+			}
+
+			if diags.HasErrors() {
+				return
+			}
+
+			for _, problem := range deep.Equal(got, test.Want) {
+				t.Errorf(problem)
+			}
+		})
+	}
+}

addrs/provider_config.go

@@ -17,6 +17,63 @@ type ProviderConfig struct {
 	Alias string
 }
 
+// NewDefaultProviderConfig returns the address of the default (un-aliased)
+// configuration for the provider with the given type name.
+func NewDefaultProviderConfig(typeName string) ProviderConfig {
+	return ProviderConfig{
+		Type: typeName,
+	}
+}
+
+// ParseProviderConfigCompact parses the given absolute traversal as a relative
+// provider address in compact form. The following are examples of traversals
+// that can be successfully parsed as compact relative provider configuration
+// addresses:
+//
+//     aws
+//     aws.foo
+//
+// This function will panic if given a relative traversal.
+//
+// If the returned diagnostics contains errors then the result value is invalid
+// and must not be used.
+func ParseProviderConfigCompact(traversal hcl.Traversal) (ProviderConfig, tfdiags.Diagnostics) {
+	var diags tfdiags.Diagnostics
+	ret := ProviderConfig{
+		Type: traversal.RootName(),
+	}
+
+	if len(traversal) < 2 {
+		// Just a type name, then.
+		return ret, diags
+	}
+
+	aliasStep := traversal[1]
+	switch ts := aliasStep.(type) {
+	case hcl.TraverseAttr:
+		ret.Alias = ts.Name
+		return ret, diags
+	default:
+		diags = diags.Append(&hcl.Diagnostic{
+			Severity: hcl.DiagError,
+			Summary:  "Invalid provider configuration address",
+			Detail:   "The provider type name must either stand alone or be followed by an alias name separated with a dot.",
+			Subject:  aliasStep.SourceRange().Ptr(),
+		})
+	}
+
+	if len(traversal) > 2 {
+		diags = diags.Append(&hcl.Diagnostic{
+			Severity: hcl.DiagError,
+			Summary:  "Invalid provider configuration address",
+			Detail:   "Extraneous extra operators after provider configuration address.",
+			Subject:  traversal[2:].SourceRange().Ptr(),
+		})
+	}
+
+	return ret, diags
+}
+
 // Absolute returns an AbsProviderConfig from the receiver and the given module
 // instance address.
 func (pc ProviderConfig) Absolute(module ModuleInstance) AbsProviderConfig {
@@ -34,6 +91,15 @@ func (pc ProviderConfig) String() string {
 	return "provider." + pc.Type
 }
 
+// StringCompact is an alternative to String that returns the form that can
+// be parsed by ParseProviderConfigCompact, without the "provider." prefix.
+func (pc ProviderConfig) StringCompact() string {
+	if pc.Alias != "" {
+		return fmt.Sprintf("%s.%s", pc.Type, pc.Alias)
+	}
+	return pc.Type
+}
+
 // AbsProviderConfig is the absolute address of a provider configuration
 // within a particular module instance.
 type AbsProviderConfig struct {

addrs/provider_config_test.go

@@ -9,6 +9,68 @@ import (
 	"github.com/hashicorp/hcl2/hcl/hclsyntax"
 )
 
+func TestParseProviderConfigCompact(t *testing.T) {
+	tests := []struct {
+		Input    string
+		Want     ProviderConfig
+		WantDiag string
+	}{
+		{
+			`aws`,
+			ProviderConfig{
+				Type: "aws",
+			},
+			``,
+		},
+		{
+			`aws.foo`,
+			ProviderConfig{
+				Type:  "aws",
+				Alias: "foo",
+			},
+			``,
+		},
+		{
+			`aws["foo"]`,
+			ProviderConfig{},
+			`The provider type name must either stand alone or be followed by an alias name separated with a dot.`,
+		},
+	}
+
+	for _, test := range tests {
+		t.Run(test.Input, func(t *testing.T) {
+			traversal, parseDiags := hclsyntax.ParseTraversalAbs([]byte(test.Input), "", hcl.Pos{})
+			if len(parseDiags) != 0 {
+				t.Errorf("unexpected diagnostics during parse")
+				for _, diag := range parseDiags {
+					t.Logf("- %s", diag)
+				}
+				return
+			}
+
+			got, diags := ParseProviderConfigCompact(traversal)
+
+			if test.WantDiag != "" {
+				if len(diags) != 1 {
+					t.Fatalf("got %d diagnostics; want 1", len(diags))
+				}
+				gotDetail := diags[0].Description().Detail
+				if gotDetail != test.WantDiag {
+					t.Fatalf("wrong diagnostic detail\ngot:  %s\nwant: %s", gotDetail, test.WantDiag)
+				}
+				return
+			} else {
+				if len(diags) != 0 {
+					t.Fatalf("got %d diagnostics; want 0", len(diags))
+				}
+			}
+
+			for _, problem := range deep.Equal(got, test.Want) {
+				t.Error(problem)
+			}
+		})
+	}
+}
 func TestParseAbsProviderConfig(t *testing.T) {
 	tests := []struct {
 		Input    string

addrs/resource.go

@@ -2,6 +2,7 @@ package addrs
 
 import (
 	"fmt"
+	"strings"
 )
 
 // Resource is an address for a resource block within configuration, which
@@ -43,6 +44,26 @@ func (r Resource) Absolute(module ModuleInstance) AbsResource {
 	}
 }
 
+// DefaultProviderConfig returns the address of the provider configuration
+// that should be used for the resource identified by the reciever if it
+// does not have a provider configuration address explicitly set in
+// configuration.
+//
+// This method is not able to verify that such a configuration exists, nor
+// represent the behavior of automatically inheriting certain provider
+// configurations from parent modules. It just does a static analysis of the
+// receiving address and returns an address to start from, relative to the
+// same module that contains the resource.
+func (r Resource) DefaultProviderConfig() ProviderConfig {
+	typeName := r.Type
+	if under := strings.Index(typeName, "_"); under != -1 {
+		typeName = typeName[:under]
+	}
+	return ProviderConfig{
+		Type: typeName,
+	}
+}
+
 // ResourceInstance is an address for a specific instance of a resource.
 // When a resource is defined in configuration with "count" or "for_each" it
 // produces zero or more instances, which can be addressed using this type.
@@ -52,6 +73,10 @@ type ResourceInstance struct {
 	Key      InstanceKey
 }
 
+func (r ResourceInstance) ContainingResource() Resource {
+	return r.Resource
+}
+
 func (r ResourceInstance) String() string {
 	if r.Key == NoKey {
 		return r.Resource.String()
@@ -70,6 +95,7 @@ func (r ResourceInstance) Absolute(module ModuleInstance) AbsResourceInstance {
 
 // AbsResource is an absolute address for a resource under a given module path.
 type AbsResource struct {
+	targetable
 	Module   ModuleInstance
 	Resource Resource
 }
@@ -86,6 +112,34 @@ func (m ModuleInstance) Resource(mode ResourceMode, typeName string, name string
 	}
 }
 
+// Instance produces the address for a specific instance of the receiver
+// that is idenfied by the given key.
+func (r AbsResource) Instance(key InstanceKey) AbsResourceInstance {
+	return AbsResourceInstance{
+		Module:   r.Module,
+		Resource: r.Resource.Instance(key),
+	}
+}
+
+// TargetContains implements Targetable by returning true if the given other
+// address is either equal to the receiver or is an instance of the
+// receiver.
+func (r AbsResource) TargetContains(other Targetable) bool {
+	switch to := other.(type) {
+
+	case AbsResource:
+		// We'll use our stringification as a cheat-ish way to test for equality.
+		return to.String() == r.String()
+
+	case AbsResourceInstance:
+		return r.TargetContains(to.ContainingResource())
+
+	default:
+		return false
+
+	}
+}
+
 func (r AbsResource) String() string {
 	if len(r.Module) == 0 {
 		return r.Resource.String()
@@ -96,6 +150,7 @@ func (r AbsResource) String() string {
 // AbsResourceInstance is an absolute address for a resource instance under a
 // given module path.
 type AbsResourceInstance struct {
+	targetable
 	Module   ModuleInstance
 	Resource ResourceInstance
 }
@@ -115,6 +170,31 @@ func (m ModuleInstance) ResourceInstance(mode ResourceMode, typeName string, nam
 	}
 }
 
+// ContainingResource returns the address of the resource that contains the
+// receving resource instance. In other words, it discards the key portion
+// of the address to produce an AbsResource value.
+func (r AbsResourceInstance) ContainingResource() AbsResource {
+	return AbsResource{
+		Module:   r.Module,
+		Resource: r.Resource.ContainingResource(),
+	}
+}
+
+// TargetContains implements Targetable by returning true if the given other
+// address is equal to the receiver.
+func (r AbsResourceInstance) TargetContains(other Targetable) bool {
+	switch to := other.(type) {
+
+	case AbsResourceInstance:
+		// We'll use our stringification as a cheat-ish way to test for equality.
+		return to.String() == r.String()
+
+	default:
+		return false
+
+	}
+}
+
 func (r AbsResourceInstance) String() string {
 	if len(r.Module) == 0 {
 		return r.Resource.String()

addrs/resource_phase.go

@@ -0,0 +1,57 @@
+package addrs
+
+import "fmt"
+
+// ResourceInstancePhase is a special kind of reference used only internally
+// during graph building to represent resource instances that are in a
+// non-primary state.
+//
+// Graph nodes can declare themselves referenceable via an instance phase
+// or can declare that they reference an instance phase in order to accomodate
+// secondary graph nodes dealing with, for example, destroy actions.
+//
+// This special reference type cannot be accessed directly by end-users, and
+// should never be shown in the UI.
+type ResourceInstancePhase struct {
+	referenceable
+	ResourceInstance ResourceInstance
+	Phase            ResourceInstancePhaseType
+}
+
+var _ Referenceable = ResourceInstancePhase{}
+
+// Phase returns a special "phase address" for the receving instance. See the
+// documentation of ResourceInstancePhase for the limited situations where this
+// is intended to be used.
+func (r ResourceInstance) Phase(rpt ResourceInstancePhaseType) ResourceInstancePhase {
+	return ResourceInstancePhase{
+		ResourceInstance: r,
+		Phase:            rpt,
+	}
+}
+
+func (rp ResourceInstancePhase) String() string {
+	// We use a different separator here than usual to ensure that we'll
+	// never conflict with any non-phased resource instance string. This
+	// is intentionally something that would fail parsing with ParseRef,
+	// because this special address type should never be exposed in the UI.
+	return fmt.Sprintf("%s#%s", rp.ResourceInstance, rp.Phase)
+}
+
+// ResourceInstancePhaseType is an enumeration used with ResourceInstancePhase.
+type ResourceInstancePhaseType string
+
+const (
+	// ResourceInstancePhaseDestroy represents the "destroy" phase of a
+	// resource instance.
+	ResourceInstancePhaseDestroy ResourceInstancePhaseType = "destroy"
+
+	// ResourceInstancePhaseDestroyCBD is similar to ResourceInstancePhaseDestroy
+	// but is used for resources that have "create_before_destroy" set, thus
+	// requiring a different dependency ordering.
+	ResourceInstancePhaseDestroyCBD ResourceInstancePhaseType = "destroy-cbd"
+)
+
+func (rpt ResourceInstancePhaseType) String() string {
+	return string(rpt)
+}

addrs/targetable.go

@@ -0,0 +1,26 @@
+package addrs
+
+// Targetable is an interface implemented by all address types that can be
+// used as "targets" for selecting sub-graphs of a graph.
+type Targetable interface {
+	targetableSigil()
+
+	// TargetContains returns true if the receiver is considered to contain
+	// the given other address. Containment, for the purpose of targeting,
+	// means that if a container address is targeted then all of the
+	// addresses within it are also implicitly targeted.
+	//
+	// A targetable address always contains at least itself.
+	TargetContains(other Targetable) bool
+
+	// String produces a string representation of the address that could be
+	// parsed as a HCL traversal and passed to ParseTarget to produce an
+	// identical result.
+	String() string
+}
+
+type targetable struct {
+}
+
+func (r targetable) targetableSigil() {
+}