feat!: key-address launchdarkly_project environments (REL-14236)

[monsagri]

Summary

Implements REL-14236 (epic REL-13579): re-model launchdarkly_project.environments from a positional list to a map keyed by environment key.

# before (v2 / early v3 preview)        # after (this PR)
environments = [{                       environments = {
  key   = "production"                    "production" = {
  name  = "Production"                      name  = "Production"
  color = "EEEEEE"                          color = "EEEEEE"
}]                                        }
                                        }

Reordering, adding, or removing one environment no longer shifts array indices and forces destructive plans on its siblings. The inner key argument moves out of the object and becomes the map key.

Behavior changes

• environments is now Optional + Computed and the non-empty (SizeAtLeast(1)) constraint is dropped.
• Manage a subset: Read refreshes only the keys already in state and the reconcile loop only deletes formerly-managed environments, so an environment created outside Terraform (e.g. via the UI) is never pulled into state and never deleted.
• environments = {} manages no environments; omitting the attribute entirely emits a plan-time warning steering toward {} or an explicit map.
• Import is order-independent (map keyed by env key), so the old ImportStateVerifyIgnore: ["environments"] workaround is gone.

Supporting changes

• migrate-tf-syntax: new map_key transform — forward hoists the block's key to the map key (dropping it from the object); reverse expands the map back to repeated blocks; positional environments[N] references are rewritten to environments["<key>"]. Non-literal keys warn + skip.
• State upgrader: v0 (SDKv2 ordered list) → v3 map, preserving the approval-settings API-defaults nulling. The v0 prior schema is pinned to the original list shape so genuine v2 state still decodes.
• Docs, examples, migration guide, and the terraform-provider-block-to-nested-attrs skill (→ 2.1.0) updated for the map syntax.

Breaking change

launchdarkly_project.environments is a map keyed by environment key instead of an ordered list; the inner key attribute is removed. Configs are rewritten with migrate-tf-syntax; the v2 → v3 state upgrade is automatic. Only the v2 → v3.0.0 GA boundary is a compatibility obligation — preview→preview state is intentionally allowed to break (existing 3.0.0-beta.N state stored as a list will not decode and must be re-imported).

Test plan

• Unit: migrate-tool map round-trip (TestForwardConvertsMapBlock, TestReverseMapBlock, non-literal skip); v0-list→map upgrader (TestEnvironmentsMapFromV0List, incl. approval-defaults nulling).
• Local: go build · go vet · make fmtcheck · terraform validate (map accepted / legacy list rejected / {} & omit accepted).
• Acceptance (CI, real LD): existing project CRUD/import/many-env tests rewritten to map keys, plus new TestAccProject_ZeroEnvironments and TestAccProject_ManageSubset (out-of-band env is ignored and not deleted). 11 sibling resources' acc fixtures updated to map syntax.

Reviewer notes / residual

• The first-Apply plan-vs-apply consistency for the Optional+Computed map with the three computed-sensitive inner fields (api_key/mobile_key/client_side_id) is exercised by TestAccProject_WithEnvironments create+import.
• There are no statecompat fixtures for any resource in this line, so the v2→v3 state upgrade is unit-tested (consistent with feat!: use object syntax for single-object flag/project attributes (REL-14237) #480).

Draft pending the CI acceptance gate.

🤖 Generated with Claude Code

---

Note

High Risk
Breaking Terraform schema with authoritative environment deletes and irreversible key changes; incorrect configs or partial maps can destroy environments and targeting in LaunchDarkly.

Overview
Breaking change: launchdarkly_project.environments moves from an ordered list / repeated blocks to a required map keyed by environment key, with at least one entry. Each value keeps an Optional+Computed inner key that must match the map key. The map is authoritative—keys dropped from config are deleted on apply (SDK keys and flag targeting), with plan-time warnings when removals or renames are detected.

Provider logic is refactored for maps: reconciliation creates new envs before deleting removed ones (so renames never leave a project with zero environments), ValidateConfig enforces map key ↔ nested key, and ModifyPlan fixes sensitive computed fields and pins key to the map key. Read/import builds a full map from the API (order-independent; flaky list-order import workarounds removed). State upgrade re-keys v0 list state to a map via environmentsMapFromV0List (incl. approval-settings default nulling).

migrate-tf-syntax gains map_key for block ↔ environments = { "prod" = { ... } } conversion; it warns on positional environments[N] / [*] refs for manual fix-up rather than rewriting them. Docs, examples, migration guide, skill 2.2.0, and acceptance tests switch to map syntax and key-based references (e.g. environments["test-env"].client_side_side_id).

^{Reviewed by Cursor Bugbot for commit 8f721db. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 48095d2. Configure here.}

[cursor]

Read imports all environments

High Severity

environmentsMapFromAPI walks every environment returned by the API and writes each into state, even when that key was never in prior state. That contradicts refresh-only-managed-keys behavior and pulls UI-created environments into state so a later authoritative apply can delete them.

Additional Locations (1)

• launchdarkly/resource_project_framework.go#L686-L695

 

^{Reviewed by Cursor Bugbot for commit 48095d2. Configure here.}

[monsagri]

This is now working as designed. Per the design review, launchdarkly_project.environments is authoritative — the map is the project's complete set of managed environments, so Read surfaces all of them and an apply deletes any not declared. Manage-a-subset was explicitly dropped as a use case. To manage the project in Terraform but its environments elsewhere (UI or the standalone launchdarkly_environment resource), use lifecycle { ignore_changes = [environments] }. A plan-time warning fires before any environment is deleted.

[devin-ai-integration]

Devin Review found 1 potential issue.

⚠️ 1 issue in files not directly in the diff

⚠️ Published example and docs for view_filter_links use broken list-index syntax on the now-map environments attribute (examples/resources/launchdarkly_view_filter_links/resource.tf:14)

The example file still references environments with positional list-index syntax (environments[0] at examples/resources/launchdarkly_view_filter_links/resource.tf:14 and :22), but this PR changed environments to a map, so users who copy the example will get a Terraform error.

Impact: Published documentation shows invalid Terraform code that fails on terraform validate.

The example file was not updated alongside the List→Map schema change

The PR converts launchdarkly_project.environments from a ListNestedAttribute to a MapNestedAttribute (launchdarkly/environments_framework.go:84). List-index access like environments[0].client_side_id is not valid for a map attribute — the correct syntax is environments["<key>"].client_side_id.

The example at examples/resources/launchdarkly_view_filter_links/resource.tf (lines 14 and 22) was not updated. Since docs/ is generated from examples/ via tfplugindocs (per CLAUDE.md), the generated docs/resources/view_filter_links.md lines 41 and 49 carry the same broken syntax into published documentation.

Every other test and example in the PR was updated to use the new map-key syntax (e.g. environments["test-env"].client_side_id), but this example was missed.