docs-drift

name

docs-drift

description

Validates confluentinc/terraform-provider-confluent's docs/ (resources, data-sources, guides) and examples against the actual Go schema definitions to catch stale references to deprecated or renamed resources/attributes, wrong/missing/extra attributes vs. schema, typos, broken links, and example .tf blocks that no longer validate against the current provider. Use when asked to check for documentation drift, validate provider docs/examples, or audit resource/data-source docs for staleness. Read-only by default — only edits a file when explicitly asked to fix something.

Docs Drift — confluentinc/terraform-provider-confluent

docs/ (resources/, data-sources/, guides/) was originally generated by tfplugindocs, but that's not wired into CI or the build today — it's effectively hand-maintained now, so drift is structurally possible even where things currently look fine. Ground truth lives in internal/provider/resource_*.go / data_source_*.go schema maps and internal/provider/provider.go's ResourcesMap/DataSourcesMap.

1. Resource/data-source presence check

Diff the type names in provider.go's ResourcesMap/DataSourcesMap against the file names under docs/resources/*.md / docs/data-sources/*.md. Flag:

• A resource/data-source in the schema with no doc page (undocumented)
• A doc page for a resource/data-source no longer in provider.go (removed but the doc was left behind — the "still references a deprecated/renamed resource" failure mode, e.g. a page for something like confluent_schema_registry_region after it was retired)

2. Attribute-level diff, per resource

For each resource/data-source, extract its attribute map from internal/provider/resource_*.go (or data_source_*.go): attribute name, Required/Optional/Computed, and any Deprecated:/DeprecationMessage string (shared messages live in internal/provider/constants.go, e.g. deprecationMessageMajorRelease3). Compare against the argument/attribute reference list in the matching docs/resources/<name>.md, below the <!-- schema generated by tfplugindocs --> marker. Flag:

• An attribute in the doc but not in the schema — renamed/removed, or a plain typo (this is how something like tableflpw_api_key shows up: the doc references a name the schema doesn't have)
• An attribute in the schema but missing from the doc (undocumented new attribute)
• Required/Optional/Computed mismatch between doc prose and schema
• Schema marks the attribute Deprecated but the doc doesn't say so, or says something stale

3. Regenerate into a scratch dir as a second opinion

tfplugindocs isn't in go.mod/a tools.go here, so don't assume it's installed — check first (command -v tfplugindocs, else go run github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs@latest). If available, generate into a scratch directory, never in place:

tfplugindocs generate --provider-dir . --rendered-website-dir /tmp/docs-drift-scratch

Only diff the schema-derived argument/attribute-reference sections against the real docs/ — hand-written example blocks will differ by construction, since there's no examples/resources/<name>/resource.tf convention here (examples are inline in the markdown), so a full-file diff would be mostly noise. Treat this as a cross-check on step 2, not a replacement for it.

4. Validate example .tf content

Two sources: inline ```terraform blocks inside docs/**/*.md, and the ~50 standalone scenarios under examples/configurations/*/.

• For both, extract resource types and attribute names used and cross-reference against the canonical names from step 2 — this is what catches a stale reference to a resource/attribute that no longer exists (the "missing quotes" and typo classes of bug also often surface here as a name that almost-but-doesn't-quite match).
• For examples/configurations/*/ (real standalone .tf files), actually validate them:

  go build -o terraform-provider-confluent
  

  then point a dev_overrides block in a temporary CLI config selected via TF_CLI_CONFIG_FILE at that binary. Each scenario still needs an initialized working directory, so run terraform init -backend=false before terraform validate. The override avoids downloading the locally built provider from the registry; initialization may still download other declared providers or modules unless they are already cached. validate doesn't need live credentials — just loadable provider schemas. A validate failure is a direct "this example no longer applies against the current provider" hit.
• For inline doc examples (not standalone files), at minimum write each block to a temp .tf file and run terraform fmt -check against it to catch syntax-level issues like missing quotes; run full terraform validate on them too if the user wants exhaustive checking, since that requires the same dev_overrides setup as above per snippet.

5. Typos and broken links

• Fuzzy-match every resource/attribute name found in docs and examples against the canonical name list from step 2 (edit distance ~1-2) to catch typos that don't happen to collide with a real different name.
• Extract [text](url) links from docs/**/*.md, including references to examples/configurations/... from guides like docs/index.md. Verify relative links resolve to real files; spot-check external links with a HEAD request.

Output

Report grouped by category — orphaned/missing doc page, attribute mismatch, deprecated-but-not-documented, example validate failure, typo, broken link — each with the resource name and file path plus a one-line concrete explanation. Stay read-only: only edit a file if the user explicitly asks you to fix something, and show the diff before/after.