Add foundational feature matrix system for generation support

- Implement IsFeatureSupported() helper function for Cedar/Fir generation differences
- Add feature matrix tracking space capabilities across generations
- Include comprehensive test coverage with 14 test cases
- Cedar generation: supports all space features including shield spaces
- Fir generation: supports private spaces only, shield spaces unsupported
- Foundation for graceful handling of generation-specific feature differences

Author: heroku-johnny

.tool-versions

@@ -0,0 +1,2 @@
+golang 1.24.5
+terraform 1.5.7

heroku/heroku_supported_features.go

@@ -0,0 +1,56 @@
+package heroku
+
+// Feature matrix system for graceful handling of generation differences
+// between Cedar and Fir generations in Terraform Provider Heroku.
+
+// featureMatrix defines which features are supported for each generation and resource type.
+// This is the single source of truth for feature availability based on the
+// unsupported features data from Platform API's 3.sdk Generation endpoints.
+var featureMatrix = map[string]map[string]map[string]bool{
+	"cedar": {
+		"space": {
+			"private":               true, // All spaces are private
+			"shield":                true, // Cedar supports shield spaces
+			"trusted_ip_ranges":     true,
+			"private_vpn":           true,
+			"outbound_rules":        true,
+			"private_space_logging": true,
+		},
+	},
+	"fir": {
+		"space": {
+			"private":               true,  // All spaces are private
+			"shield":                false, // Fir does not support shield spaces
+			"trusted_ip_ranges":     false, // trusted_ip_ranges
+			"private_vpn":           false, // private_vpn
+			"outbound_rules":        false, // outbound_rules
+			"private_space_logging": false, // private_space_logging
+		},
+	},
+}
+
+// IsFeatureSupported checks if a feature is supported for a given generation and resource type.
+// Returns true if the feature is supported, false otherwise.
+//
+// Parameters:
+//   - generation: "cedar" or "fir"
+//   - resourceType: "space", "app", "build", etc.
+//   - feature: "shield", "trusted_ip_ranges", "private_vpn", etc.
+//
+// Example:
+//
+//	if IsFeatureSupported("fir", "space", "shield") {
+//	    // proceed with shield configuration
+//	}
+func IsFeatureSupported(generation, resourceType, feature string) bool {
+	if gen, exists := featureMatrix[generation]; exists {
+		if res, exists := gen[resourceType]; exists {
+			if supported, exists := res[feature]; exists {
+				return supported
+			}
+		}
+	}
+
+	// Default to false for any unknown generation/resource/feature combination
+	return false
+}

heroku/heroku_supported_features_test.go

@@ -0,0 +1,178 @@
+package heroku
+
+import (
+	"testing"
+)
+
+func TestIsFeatureSupported(t *testing.T) {
+	testCases := []struct {
+		name         string
+		generation   string
+		resourceType string
+		feature      string
+		expected     bool
+	}{
+		// Cedar generation tests - all space features supported
+		{
+			name:         "Cedar space private should be supported",
+			generation:   "cedar",
+			resourceType: "space",
+			feature:      "private",
+			expected:     true,
+		},
+		{
+			name:         "Cedar space shield should be supported",
+			generation:   "cedar",
+			resourceType: "space",
+			feature:      "shield",
+			expected:     true,
+		},
+		{
+			name:         "Cedar space trusted_ip_ranges should be supported",
+			generation:   "cedar",
+			resourceType: "space",
+			feature:      "trusted_ip_ranges",
+			expected:     true,
+		},
+
+		// Fir generation tests - private supported, shield and others unsupported
+		{
+			name:         "Fir space private should be supported",
+			generation:   "fir",
+			resourceType: "space",
+			feature:      "private",
+			expected:     true,
+		},
+		{
+			name:         "Fir space shield should be unsupported",
+			generation:   "fir",
+			resourceType: "space",
+			feature:      "shield",
+			expected:     false,
+		},
+		{
+			name:         "Fir space trusted_ip_ranges should be unsupported",
+			generation:   "fir",
+			resourceType: "space",
+			feature:      "trusted_ip_ranges",
+			expected:     false,
+		},
+
+		// Unsupported feature tests (features not in matrix)
+		{
+			name:         "Cedar space unknown_feature should be unsupported (not in matrix)",
+			generation:   "cedar",
+			resourceType: "space",
+			feature:      "unknown_feature",
+			expected:     false,
+		},
+		{
+			name:         "Fir space unknown_feature should be unsupported (not in matrix)",
+			generation:   "fir",
+			resourceType: "space",
+			feature:      "unknown_feature",
+			expected:     false,
+		},
+
+		// Unknown resource type tests
+		{
+			name:         "Cedar app features should be unsupported (not implemented yet)",
+			generation:   "cedar",
+			resourceType: "app",
+			feature:      "some_feature",
+			expected:     false,
+		},
+		{
+			name:         "Fir build features should be unsupported (not implemented yet)",
+			generation:   "fir",
+			resourceType: "build",
+			feature:      "some_feature",
+			expected:     false,
+		},
+
+		// Invalid generation tests
+		{
+			name:         "Invalid generation should be unsupported",
+			generation:   "invalid",
+			resourceType: "space",
+			feature:      "shield",
+			expected:     false,
+		},
+		{
+			name:         "Empty generation should be unsupported",
+			generation:   "",
+			resourceType: "space",
+			feature:      "shield",
+			expected:     false,
+		},
+
+		// Edge case tests
+		{
+			name:         "Empty resource type should be unsupported",
+			generation:   "cedar",
+			resourceType: "",
+			feature:      "shield",
+			expected:     false,
+		},
+		{
+			name:         "Empty feature should be unsupported",
+			generation:   "cedar",
+			resourceType: "space",
+			feature:      "",
+			expected:     false,
+		},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			result := IsFeatureSupported(tc.generation, tc.resourceType, tc.feature)
+			if result != tc.expected {
+				t.Errorf("IsFeatureSupported(%q, %q, %q) = %v, expected %v",
+					tc.generation, tc.resourceType, tc.feature, result, tc.expected)
+			}
+		})
+	}
+}
+
+// TestFeatureMatrixConsistency ensures the feature matrix is internally consistent
+func TestFeatureMatrixConsistency(t *testing.T) {
+	// Verify that all generations have at least one resource
+	for generation, resources := range featureMatrix {
+		if len(resources) == 0 {
+			t.Errorf("Generation %s has no resources defined", generation)
+		}
+
+		// Verify that all resources have at least one feature
+		for resourceType, features := range resources {
+			if len(features) == 0 {
+				t.Errorf("Generation %s, resource %s has no features defined", generation, resourceType)
+			}
+
+			// Verify that all features are properly set (no nil values)
+			for feature, supported := range features {
+				if feature == "" {
+					t.Errorf("Generation %s, resource %s has empty feature name", generation, resourceType)
+				}
+				// supported is bool, so just verify it's not accidentally unset in a way that would matter
+				_ = supported // This is intentional - we're just ensuring the value exists
+			}
+		}
+	}
+
+	// Verify minimum required features exist for Task 1
+	// Both generations support private spaces
+	if !IsFeatureSupported("cedar", "space", "private") {
+		t.Error("Cedar space private must be supported")
+	}
+	if !IsFeatureSupported("fir", "space", "private") {
+		t.Error("Fir space private must be supported")
+	}
+
+	// Only cedar supports shield spaces
+	if !IsFeatureSupported("cedar", "space", "shield") {
+		t.Error("Cedar space shield must be supported")
+	}
+	if IsFeatureSupported("fir", "space", "shield") {
+		t.Error("Fir space shield must be unsupported")
+	}
+}