terraform: Add deprecation Go documentation comments

Reference: #165

Except in certain known provider testing use cases without replacement (yet), this deprecates various `terraform` package functionality. The `terraform` package contains legacy Terraform core logic which has been copied to terraform-plugin-sdk and terraform-plugin-testing over the years and continually exported due to the complexity of rewriting developer functionality using the machine-readable interfaces for Terraform, such as JSON state. Much of this now-deprecated `terraform` package logic should have been omitted when this Go module was created, but that step was missed, so it is left as-is with deprecation notices following the Go module versioning guidelines. In reality, the entire `terraform` package will be removed in a future major version, however this change pragmatically leaves certain functionality without deprecation notices for now until  replacement functionality is available so developers will not need to silence linting tools without it being actionable yet.

If there is a valid use case for this functionality, developers should create a GitHub issue for tracking.

helper/resource/state_shim.go

@@ -21,7 +21,7 @@ type shimmedState struct {
 }
 
 func shimStateFromJson(jsonState *tfjson.State) (*terraform.State, error) {
-	state := terraform.NewState()
+	state := terraform.NewState() //nolint:staticcheck // legacy usage
 	state.TFVersion = jsonState.TerraformVersion
 
 	if jsonState.Values == nil {
@@ -124,7 +124,7 @@ func (ss *shimmedState) shimStateModule(sm *tfjson.StateModule) error {
 		}
 	}
 
-	mod := ss.state.AddModule(path)
+	mod := ss.state.AddModule(path) //nolint:staticcheck // legacy usage
 	for _, res := range sm.Resources {
 		resourceState, err := shimResourceState(res)
 		if err != nil {

helper/resource/testing.go

@@ -1548,7 +1548,7 @@ func testCheckResourceAttrPair(isFirst *terraform.InstanceState, nameFirst strin
 // TestCheckOutput checks an output in the Terraform configuration
 func TestCheckOutput(name, value string) TestCheckFunc {
 	return func(s *terraform.State) error {
-		ms := s.RootModule()
+		ms := s.RootModule() //nolint:staticcheck // legacy usage
 		rs, ok := ms.Outputs[name]
 		if !ok {
 			return fmt.Errorf("Not found: %s", name)
@@ -1568,7 +1568,7 @@ func TestCheckOutput(name, value string) TestCheckFunc {
 
 func TestMatchOutput(name string, r *regexp.Regexp) TestCheckFunc {
 	return func(s *terraform.State) error {
-		ms := s.RootModule()
+		ms := s.RootModule() //nolint:staticcheck // legacy usage
 		rs, ok := ms.Outputs[name]
 		if !ok {
 			return fmt.Errorf("Not found: %s", name)
@@ -1610,7 +1610,7 @@ func modulePrimaryInstanceState(ms *terraform.ModuleState, name string) (*terraf
 // modulePathPrimaryInstanceState returns the primary instance state for the
 // given resource name in a given module path.
 func modulePathPrimaryInstanceState(s *terraform.State, mp addrs.ModuleInstance, name string) (*terraform.InstanceState, error) {
-	ms := s.ModuleByPath(mp)
+	ms := s.ModuleByPath(mp) //nolint:staticcheck // legacy usage
 	if ms == nil {
 		return nil, fmt.Errorf("No module found at: %s", mp)
 	}
@@ -1621,7 +1621,7 @@ func modulePathPrimaryInstanceState(s *terraform.State, mp addrs.ModuleInstance,
 // primaryInstanceState returns the primary instance state for the given
 // resource name in the root module.
 func primaryInstanceState(s *terraform.State, name string) (*terraform.InstanceState, error) {
-	ms := s.RootModule()
+	ms := s.RootModule() //nolint:staticcheck // legacy usage
 	return modulePrimaryInstanceState(ms, name)
 }
 
@@ -1640,7 +1640,7 @@ func indexesIntoTypeSet(key string) bool {
 func checkIfIndexesIntoTypeSet(key string, f TestCheckFunc) TestCheckFunc {
 	return func(s *terraform.State) error {
 		err := f(s)
-		if err != nil && s.IsBinaryDrivenTest && indexesIntoTypeSet(key) {
+		if err != nil && indexesIntoTypeSet(key) {
 			return fmt.Errorf("Error in test check: %s\nTest check address %q likely indexes into TypeSet\nThis is currently not possible in the SDK", err, key)
 		}
 		return err
@@ -1650,7 +1650,7 @@ func checkIfIndexesIntoTypeSet(key string, f TestCheckFunc) TestCheckFunc {
 func checkIfIndexesIntoTypeSetPair(keyFirst, keySecond string, f TestCheckFunc) TestCheckFunc {
 	return func(s *terraform.State) error {
 		err := f(s)
-		if err != nil && s.IsBinaryDrivenTest && (indexesIntoTypeSet(keyFirst) || indexesIntoTypeSet(keySecond)) {
+		if err != nil && (indexesIntoTypeSet(keyFirst) || indexesIntoTypeSet(keySecond)) {
 			return fmt.Errorf("Error in test check: %s\nTest check address %q or %q likely indexes into TypeSet\nThis is currently not possible in the SDK", err, keyFirst, keySecond)
 		}
 		return err

helper/resource/testing_new.go

@@ -356,7 +356,7 @@ func getState(ctx context.Context, t testing.T, wd *plugintest.WorkingDir) (*ter
 }
 
 func stateIsEmpty(state *terraform.State) bool {
-	return state.Empty() || !state.HasResources()
+	return state.Empty() || !state.HasResources() //nolint:staticcheck // legacy usage
 }
 
 func planIsEmpty(plan *tfjson.Plan) bool {
@@ -375,7 +375,7 @@ func testIDRefresh(ctx context.Context, t testing.T, c TestCase, wd *plugintest.
 
 	// Build the state. The state is just the resource with an ID. There
 	// are no attributes. We only set what is needed to perform a refresh.
-	state := terraform.NewState()
+	state := terraform.NewState() //nolint:staticcheck // legacy usage
 	state.RootModule().Resources = make(map[string]*terraform.ResourceState)
 	state.RootModule().Resources[c.IDRefreshName] = &terraform.ResourceState{}
 

helper/resource/testing_new_config.go

@@ -112,7 +112,6 @@ func testStepNewConfig(ctx context.Context, t testing.T, c TestCase, wd *plugint
 		if step.Check != nil {
 			logging.HelperResourceTrace(ctx, "Using TestStep Check")
 
-			state.IsBinaryDrivenTest = true
 			if step.Destroy {
 				if err := step.Check(stateBeforeApplication); err != nil {
 					return fmt.Errorf("Check failed: %w", err)
@@ -244,6 +243,7 @@ func testStepNewConfig(ctx context.Context, t testing.T, c TestCase, wd *plugint
 			return err
 		}
 
+		//nolint:staticcheck // legacy usage
 		if state.Empty() {
 			return nil
 		}

helper/resource/testing_new_import_state.go

@@ -147,7 +147,7 @@ func testStepNewImportState(ctx context.Context, t testing.T, helper *plugintest
 				continue
 			}
 
-			is := r.Primary.DeepCopy()
+			is := r.Primary.DeepCopy() //nolint:staticcheck // legacy usage
 			is.Ephemeral.Type = r.Type // otherwise the check function cannot see the type
 			states = append(states, is)
 		}