Add support for --provider-schema flag and context to generate sub-command errors (#299)

* Add context to errors

* Refactor to use `g.providerName` instead of passing the provider name as a parameter.

* Add support for `--providers-schema` flag to pass in a providers schema JSON file.

* Add schema json acceptance tests and move provider build tests into a separate folder.

* Update README.md

* Add copyright headers

* Add more schema json tests

* Add changelog entry

* Apply documentation suggestions

Co-authored-by: Brian Flad <[email protected]>

---------

Co-authored-by: Brian Flad <[email protected]>

Author: SBGoods

.changes/unreleased/ENHANCEMENTS-20231117-151029.yaml

@@ -0,0 +1,6 @@
+kind: ENHANCEMENTS
+body: 'generate: Add `provider-schema` flag to pass in a file path to a provider schema JSON
+  file, allowing the command to skip building the provider and calling Terraform CLI'
+time: 2023-11-17T15:10:29.850914-05:00
+custom:
+  Issue: "299"

README.md

@@ -43,6 +43,7 @@ Usage: tfplugindocs generate [<args>]
     --ignore-deprecated <ARG>        don't generate documentation for deprecated resources and data-sources                                                             (default: "false")
     --provider-dir <ARG>             relative or absolute path to the root provider code directory when running the command outside the root provider code directory  
     --provider-name <ARG>            provider name, as used in Terraform configurations                                                                               
+    --providers-schema <ARG>         path to the providers schema JSON file, which contains the output of the terraform providers schema -json command. Setting this flag will skip building the provider and calling Terraform CLI                                                                               
     --rendered-provider-name <ARG>   provider name, as generated in documentation (ex. page titles, ...)                                                              
     --rendered-website-dir <ARG>     output directory based on provider-dir                                                                                             (default: "docs")
     --tf-version <ARG>               terraform binary version to download                                                                                             
@@ -198,9 +199,15 @@ This can be autogenerated by running `make generate` or running `go generate ./.
 
 This repo uses the `testscript` [package](https://pkg.go.dev/github.com/rogpeppe/go-internal/testscript) for acceptance testing.
 
-You can run `make testacc` to run the acceptance tests. By default, the acceptance tests will create a temporary directory in `/tmp/tftmp` for testing but you can change this location in `cmd/tfplugindocs/main_test.go`
+There are two types of acceptance tests: full provider build tests in `tfplugindocs/testdata/scripts/provider-build` and provider schema json tests in `tfplugindocs/testdata/scripts/schema-json`.
 
-The test scripts are defined in the `tfplugindocs/testdata/scripts` directory. Each script includes the test, golden files, and the provider source code needed to run the test.
+Provider build tests run the default `tfplugindocs` command which builds the provider source code and runs Terraform to retrieve the schema. These tests require the full provider source code to build a valid provider binary. 
+
+Schema json tests run the `tfplugindocs` command with the `--providers-schema=<arg>` flag to specify a provider schemas json file. This allows the test to skip the provider build and Terraform CLI call, instead using the specified file to generate docs. 
+
+You can run `make testacc` to run the full suite of acceptance tests. By default, the provider build acceptance tests will create a temporary directory in `/tmp/tftmp` for testing, but you can change this location in `cmd/tfplugindocs/main_test.go`. The schema json tests uses the `testscript` package's [default work directory](https://pkg.go.dev/github.com/rogpeppe/go-internal/testscript#Params.WorkdirRoot).
+
+The test scripts are defined in the `tfplugindocs/testdata/scripts` directory. Each script includes the test, golden files, and the provider source code or schema JSON file needed to run the test.
 
 Each script is a [text archive](https://pkg.go.dev/golang.org/x/tools/txtar). You can install the `txtar` CLI locally by running `go install golang.org/x/exp/cmd/txtar@latest` to extract the files in the test script for debugging. 
 You can also use `txtar` CLI archive files into the `.txtar` format to create new tests or modify existing ones.

cmd/tfplugindocs/main_test.go

@@ -18,10 +18,10 @@ func TestMain(m *testing.M) {
 	}))
 }
 
-func Test_GenerateAcceptanceTests(t *testing.T) {
+func Test_ProviderBuild_GenerateAcceptanceTests(t *testing.T) {
 	t.Parallel()
 	if os.Getenv("ACCTEST") == "" {
-		t.Skip("ACCTEST env var not set; skipping acceptance tests.")
+		t.Skip("ACCTEST env var not set; skipping provider build acceptance tests.")
 	}
 	// Setting a custom temp dir instead of relying on os.TempDir()
 	// because Terraform providers fail to start up when $TMPDIR
@@ -34,7 +34,15 @@ func Test_GenerateAcceptanceTests(t *testing.T) {
 	defer os.RemoveAll(tmpDir)
 
 	testscript.Run(t, testscript.Params{
-		Dir:         "testdata/scripts/generate",
+		Dir:         "testdata/scripts/provider-build/generate",
 		WorkdirRoot: tmpDir,
 	})
 }
+
+func Test_SchemaJson_GenerateAcceptanceTests(t *testing.T) {
+	t.Parallel()
+
+	testscript.Run(t, testscript.Params{
+		Dir: "testdata/scripts/schema-json/generate",
+	})
+}