all: Add support for state stores (#570)

* initial impl and basic test skips

* add tests and changelogs

* add generate tests

* add migrate and validate tests

* update changelogs with PR

* fmt

Author: austinvalle

.changes/unreleased/FEATURES-20260227-144449.yaml

@@ -0,0 +1,5 @@
+kind: FEATURES
+body: 'generate: Add support for state stores'
+time: 2026-02-27T14:44:49.221116-05:00
+custom:
+    Issue: "570"

.changes/unreleased/FEATURES-20260227-144513.yaml

@@ -0,0 +1,5 @@
+kind: FEATURES
+body: 'migrate: Add support for state stores'
+time: 2026-02-27T14:45:13.780708-05:00
+custom:
+    Issue: "570"

.changes/unreleased/FEATURES-20260227-144523.yaml

@@ -0,0 +1,5 @@
+kind: FEATURES
+body: 'validate: Add support for state stores'
+time: 2026-02-27T14:45:23.218741-05:00
+custom:
+    Issue: "570"

README.md

@@ -119,6 +119,7 @@ When you run `tfplugindocs`, by default from the root directory of a provider co
 * Generate ephemeral resource template files, if missing (Requires Terraform v1.10.0+)
 * Generate action template files, if missing (Requires Terraform v1.14.0+)
 * Generate list resource templeate files, if missing (Requires Terraform v1.14.0+)
+* Generate state store template files, if missing (Requires Terraform v1.16.0+)
 * Copy all non-template files to the output website directory
 
 > [!NOTE]
@@ -219,6 +220,8 @@ For templates:
 | `templates/functions/<function name>.md[.tmpl]`                     | Function page (or template)                   |
 | `templates/list-resources.md[.tmpl]`                                | Generic list resource page (or template)      |
 | `templates/list-resources/<list resource name>.md[.tmpl]`           | List resource page (or template)              |
+| `templates/state-stores.md[.tmpl]`                                  | Generic state store page (or template)        |
+| `templates/state-stores/<state store name>.md[.tmpl]`               | State store page (or template)                |
 | `templates/resources.md[.tmpl]`                                     | Generic resource page (or template)           |
 | `templates/resources/<resource name>.md[.tmpl]`                     | Resource page (or template)                   |
 
@@ -238,6 +241,7 @@ For examples:
 | `examples/ephemeral-resources/<ephemeral resource>/ephemeral-resource<*>.tf` | Ephemeral resource example config(s)       |
 | `examples/functions/<function name>/function<*>.tf`                          | Function example config(s)                 |
 | `examples/list-resources/<list resource>/list-resource<*>.tfquery.hcl`       | List resource example config(s)            |
+| `examples/state-stores/<state store>/state-store<*>.tf`                      | State store example config(s)              |
 | `examples/resources/<resource name>/resource<*>.tf`                          | Resource example config(s)                 |
 | `examples/resources/<resource name>/import.sh`                               | Resource example import command            |
 | `examples/resources/<resource name>/import-by-string-id.tf`                  | Resource example import by id config       |
@@ -262,6 +266,7 @@ Legacy website directory structure:
 | `website/docs/ephemeral-resources/<ephemeral resource name>.html.markdown` | Ephemeral resource page     |
 | `website/docs/functons/<function name>.html.markdown`                      | Functions page              |
 | `website/docs/list-resources/<list resource name>.html.markdown`           | List resource page          |
+| `website/docs/state-stores/<state store name>.html.markdown`               | State store page            |
 | `website/docs/r/<resource name>.html.markdown`                             | Resource page               |
 
 Docs website directory structure:
@@ -276,6 +281,7 @@ Docs website directory structure:
 | `docs/ephemeral-resources/<ephemeral resource name>.html.markdown` | Ephemeral resource page     |
 | `docs/functions/<function name>.html.markdown`                     | Function page               |
 | `docs/list-resources/<list resource name>.html.markdown`           | List resource page          |
+| `docs/state-stores/<state store name>.html.markdown`               | State store page            |
 | `docs/resources/<resource name>.html.markdown`                     | Resource page               |
 
 Files named `index` (before the first `.`) in the website docs root directory and files in the `website/docs/d/`, `website/docs/r/`, `docs/data-sources/`,
@@ -381,6 +387,22 @@ using the following data fields and functions:
 | `.RenderedProviderName` | string | Value provided via argument `--rendered-provider-name`, otherwise same as `.ProviderName`                                                      |
 | `.SchemaMarkdown`       | string | a Markdown formatted list resource Schema definition                                                                                           |
 
+##### State Store Fields
+
+| Field                   | Type   | Description                                                                                                                                    |
+|-------------------------|--------|------------------------------------------------------------------------------------------------------------------------------------------------|
+| `.Name`                 | string | Name of the state store (ex. `examplecloud_thing`)                                                                                           |
+| `.Type`                 | string | `State Store`                                                                                                                                |
+| `.Description`          | string | State store description                                                                                                                      |
+| `.HasExample`           | bool   | (Legacy) Is there an example file?                                                                                                             |
+| `.HasExamples`          | bool   | Are there example files? Always true if HasExample is true.                                                                                    |
+| `.ExampleFile`          | string | (Legacy) Path to the file with the terraform configuration example                                                                             |
+| `.ExampleFiles`         | string | Paths to the files with terraform configuration examples. Includes ExampleFile. |
+| `.ProviderName`         | string | Canonical provider name (ex. `terraform-provider-http`)                                                                                      |
+| `.ProviderShortName`    | string | Short version of the rendered provider name (ex. `http`)                                                                                     |
+| `.RenderedProviderName` | string | Value provided via argument `--rendered-provider-name`, otherwise same as `.ProviderName`                                                      |
+| `.SchemaMarkdown`       | string | a Markdown formatted state store Schema definition                                                                                           |
+
 #### Template Functions
 
 | Function        | Example                                          | Description                                                                                       |

cmd/tfplugindocs/testdata/scripts/provider-build/generate/framework_provider_success_generic_templates.txtar

@@ -29,6 +29,7 @@ generating missing function content
 generating missing ephemeral resource content
 generating missing action content
 generating missing list resource content
+generating missing state store content
 generating missing provider content
 provider "terraform-provider-scaffolding" template exists, skipping
 rendering static website

cmd/tfplugindocs/testdata/scripts/provider-build/generate/framework_provider_success_named_templates.txtar

@@ -29,6 +29,7 @@ generating missing function content
 generating missing ephemeral resource content
 generating missing action content
 generating missing list resource content
+generating missing state store content
 generating missing provider content
 provider "terraform-provider-scaffolding" template exists, skipping
 rendering static website

cmd/tfplugindocs/testdata/scripts/provider-build/generate/framework_provider_success_no_templates.txtar

@@ -27,6 +27,7 @@ generating missing function content
 generating missing ephemeral resource content
 generating missing action content
 generating missing list resource content
+generating missing state store content
 generating missing provider content
 generating new template for "terraform-provider-scaffolding"
 rendering static website

cmd/tfplugindocs/testdata/scripts/provider-build/generate/null_provider_success.txtar

@@ -26,6 +26,7 @@ generating missing function content
 generating missing ephemeral resource content
 generating missing action content
 generating missing list resource content
+generating missing state store content
 generating missing provider content
 provider "terraform-provider-null" template exists, skipping
 rendering static website
@@ -2404,4 +2405,4 @@ func main() {
 	if err != nil {
 		log.Fatal(err)
 	}
-}
+}

cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_all_framework_types.txtar

@@ -22,6 +22,7 @@ generating new template for function "scaffolding"
 generating missing ephemeral resource content
 generating missing action content
 generating missing list resource content
+generating missing state store content
 generating missing provider content
 generating new template for "terraform-provider-scaffolding"
 rendering static website

cmd/tfplugindocs/testdata/scripts/schema-json/generate/framework_provider_success_generic_templates.txtar

@@ -13,6 +13,7 @@ cmpenv docs/functions/example.md expected-function.md
 cmpenv docs/ephemeral-resources/example.md expected-ephemeral-resource.md
 cmpenv docs/actions/example.md expected-action.md
 cmpenv docs/list-resources/example.md expected-list-resource.md
+cmpenv docs/state-stores/example.md expected-state-store.md
 
 
 -- expected-output.txt --
@@ -33,6 +34,8 @@ generating missing action content
 action "scaffolding_example" fallback template exists, creating template
 generating missing list resource content
 list resource "scaffolding_example" fallback template exists, creating template
+generating missing state store content
+state store "scaffolding_example" fallback template exists, creating template
 generating missing provider content
 provider "terraform-provider-scaffolding" template exists, skipping
 rendering static website
@@ -45,6 +48,7 @@ rendering "functions/example.md.tmpl"
 rendering "index.md.tmpl"
 rendering "list-resources/example.md.tmpl"
 rendering "resources/example.md.tmpl"
+rendering "state-stores/example.md.tmpl"
 -- expected-action.md --
 # Data Fields
 
@@ -149,6 +153,60 @@ list "scaffolding_example" "example" {
   }
 }
 ```
+-- expected-state-store.md --
+# Data Fields
+
+Name: scaffolding_example
+Type: State Store
+Description: Example state store
+HasExample: true
+ExampleFile: $WORK/examples/state-stores/scaffolding_example/state-store.tf
+ProviderName: terraform-provider-scaffolding
+ProviderShortName: scaffolding
+RenderedProviderName: terraform-provider-scaffolding
+SchemaMarkdown: <!-- schema generated by tfplugindocs -->
+## Schema
+
+### Optional
+
+- `configurable_attribute` (String) Example configurable attribute
+- `defaulted` (String) Example configurable attribute with default value
+
+
+
+# Functions
+
+lower: state store
+plainmarkdown: State Store
+prefixlines: Prefix: State Store
+split: [scaffolding example]
+title: State Store
+trimspace: State Store
+upper: STATE STORE
+
+# Conditionals and File Functions
+
+printf tffile:
+## Example Usage
+
+{{tffile "$WORK/examples/state-stores/scaffolding_example/state-store.tf"}}
+
+tffile:
+## Example Usage
+
+```terraform
+terraform {
+  required_providers {
+    scaffolding = {
+      source = "registry.terraform.io/hashicorp/scaffolding"
+    }
+  }
+  state_store "scaffolding_example" {
+    configurable_attribute = "some-value"
+    provider "scaffolding" {}
+  }
+}
+```
 -- expected-datasource.md --
 # Data Fields
 
@@ -458,6 +516,44 @@ tffile:
 {{ if .HasExample -}}
 ## Example Usage
 
+{{tffile .ExampleFile }}
+{{- end }}
+-- templates/state-stores.md.tmpl --
+# Data Fields
+
+Name: {{.Name}}
+Type: {{.Type}}
+Description: {{.Description}}
+HasExample: {{.HasExample}}
+ExampleFile: {{.ExampleFile}}
+ProviderName: {{.ProviderName}}
+ProviderShortName: {{.ProviderShortName}}
+RenderedProviderName: {{.RenderedProviderName}}
+SchemaMarkdown: {{.SchemaMarkdown}}
+
+# Functions
+
+lower: {{ .Type | lower }}
+plainmarkdown: {{ .Type | plainmarkdown }}
+prefixlines: {{ .Type | prefixlines "Prefix: " }}
+split: {{ split .Name "_" }}
+title: {{ .Type | title }}
+trimspace: {{ .Type | trimspace }}
+upper: {{ .Type | upper }}
+
+# Conditionals and File Functions
+
+printf tffile:
+{{ if .HasExample -}}
+## Example Usage
+
+{{ printf "{{tffile %q}}" .ExampleFile }}
+{{- end }}
+
+tffile:
+{{ if .HasExample -}}
+## Example Usage
+
 {{tffile .ExampleFile }}
 {{- end }}
 -- templates/actions.md.tmpl --
@@ -774,6 +870,18 @@ list "scaffolding_example" "example" {
     required_attr = "some-value"
   }
 }
+-- examples/state-stores/scaffolding_example/state-store.tf --
+terraform {
+  required_providers {
+    scaffolding = {
+      source = "registry.terraform.io/hashicorp/scaffolding"
+    }
+  }
+  state_store "scaffolding_example" {
+    configurable_attribute = "some-value"
+    provider "scaffolding" {}
+  }
+}
 -- examples/data-sources/scaffolding_example/data-source.tf --
 data "scaffolding_example" "example" {
   configurable_attribute = "some-value"
@@ -848,6 +956,30 @@ resource "scaffolding_example" "example" {
                     }
                 }
             },
+            "state_store_schemas": {
+                "scaffolding_example": {
+                    "version": 0,
+                    "block": {
+                        "attributes": {
+                            "configurable_attribute": {
+                                "type": "string",
+                                "description": "Example configurable attribute",
+                                "description_kind": "markdown",
+                                "optional": true
+                            },
+                            "defaulted": {
+                                "type": "string",
+                                "description": "Example configurable attribute with default value",
+                                "description_kind": "markdown",
+                                "optional": true,
+                                "computed": true
+                            }
+                        },
+                        "description": "Example state store",
+                        "description_kind": "markdown"
+                    }
+                }
+            },
             "action_schemas": {
                 "scaffolding_example": {
                     "version": 0,
@@ -975,4 +1107,4 @@ resource "scaffolding_example" "example" {
             }
         }
     }
-}
+}