pangea-core 0.2.0 → 0.3.0

data/lib/pangea/testing/architecture_spec_generator.rb

@@ -0,0 +1,237 @@
+# frozen_string_literal: true
+
+module Pangea
+  module Testing
+    # Auto-generates RSpec architecture specs from composition metadata.
+    #
+    # Usage:
+    #   generator = ArchitectureSpecGenerator.new(
+    #     module_name: 'Pangea::Architectures::K3sDevCluster',
+    #     required_config: { cluster_name: 'test', account_id: '123456789012', ... },
+    #     expected_resources: {
+    #       'aws_vpc' => ['test-vpc'],
+    #       'aws_subnet' => ['test-public'],
+    #       'aws_iam_role' => ['test-node'],
+    #     },
+    #     expected_refs: [:vpc, :subnet, :iam],
+    #     required_tags: %w[ManagedBy Purpose Environment],
+    #     security_invariants: [
+    #       { type: :no_wildcard_actions },
+    #       { type: :no_public_ssh },
+    #       { type: :encrypted_volumes },
+    #     ],
+    #   )
+    #   puts generator.generate
+    #
+    class ArchitectureSpecGenerator
+      attr_reader :config
+
+      def initialize(**config)
+        @config = config
+      end
+
+      def generate
+        [header, synthesis_spec, security_spec].compact.join("\n\n")
+      end
+
+      def generate_synthesis
+        [header, synthesis_spec].join("\n")
+      end
+
+      def generate_security
+        [header, security_spec].join("\n")
+      end
+
+      private
+
+      def module_name = config[:module_name]
+      def required_config = config[:required_config] || {}
+      def expected_resources = config[:expected_resources] || {}
+      def expected_refs = config[:expected_refs] || []
+      def required_tags = config[:required_tags] || %w[ManagedBy Purpose Environment]
+      def security_invariants = config[:security_invariants] || []
+
+      def header
+        <<~RUBY
+          # frozen_string_literal: true
+          # Auto-generated by Pangea::Testing::ArchitectureSpecGenerator
+
+          require 'spec_helper'
+        RUBY
+      end
+
+      def synthesis_spec
+        tests = []
+        tests << terraform_structure_test
+        expected_resources.each { |type, names| names.each { |n| tests << resource_exists_test(type, n) } }
+        tests << returns_refs_test unless expected_refs.empty?
+        tests << determinism_test
+        tests << tag_test unless required_tags.empty?
+        tests << validation_tests
+
+        <<~RUBY
+          RSpec.describe #{module_name} do
+            include Pangea::Testing::SynthesisTestHelpers
+
+            describe '.build' do
+              let(:synth) { create_synthesizer }
+              let(:default_config) { #{format_hash(required_config)} }
+              let(:result) do
+                described_class.build(synth, default_config)
+                normalize_synthesis(synth.synthesis)
+              end
+
+          #{tests.map { |t| indent(t, 4) }.join("\n\n")}
+            end
+          end
+        RUBY
+      end
+
+      def security_spec
+        return nil if security_invariants.empty?
+        sec_tests = security_invariants.map { |inv| security_test(inv) }
+        <<~RUBY
+          RSpec.describe '#{module_name.split('::').last} security invariants' do
+            include Pangea::Testing::SynthesisTestHelpers
+
+            let(:synth) { create_synthesizer }
+            let(:config) { #{format_hash(required_config)} }
+            let(:result) do
+              #{module_name}.build(synth, config)
+              normalize_synthesis(synth.synthesis)
+            end
+
+          #{sec_tests.map { |t| indent(t, 2) }.join("\n\n")}
+          end
+        RUBY
+      end
+
+      def terraform_structure_test
+        <<~RUBY
+          it 'produces valid Terraform JSON' do
+            validate_terraform_structure(result, :resource)
+          end
+        RUBY
+      end
+
+      def resource_exists_test(type, name)
+        <<~RUBY
+          it 'creates #{type} #{name}' do
+            validate_resource_structure(result, '#{type}', '#{name}')
+          end
+        RUBY
+      end
+
+      def returns_refs_test
+        ref_assertions = expected_refs.map { |r| "  expect(refs).to have_key(:#{r})" }.join("\n")
+        <<~RUBY
+          it 'returns all expected resource references' do
+            refs = described_class.build(synth, default_config)
+          #{ref_assertions}
+          end
+        RUBY
+      end
+
+      def determinism_test
+        <<~RUBY
+          it 'produces deterministic output' do
+            s1 = create_synthesizer
+            described_class.build(s1, default_config)
+
+            s2 = create_synthesizer
+            described_class.build(s2, default_config)
+
+            expect(s1.synthesis.to_json).to eq(s2.synthesis.to_json)
+          end
+        RUBY
+      end
+
+      def tag_test
+        tag_assertions = required_tags.map { |t| "  expect(tagged_resource['tags']).to have_key('#{t}')" }.join("\n")
+        <<~RUBY
+          it 'applies required tags' do
+            # Check first resource type for tags
+            all_resources = result['resource'] || {}
+            tagged_resource = all_resources.values.first&.values&.first
+            next unless tagged_resource&.key?('tags')
+          #{tag_assertions}
+          end
+        RUBY
+      end
+
+      def validation_tests
+        <<~RUBY
+          context 'validation' do
+            it 'raises on empty config' do
+              expect { described_class.build(synth, {}) }.to raise_error(ArgumentError)
+            end
+          end
+        RUBY
+      end
+
+      def security_test(invariant)
+        case invariant[:type]
+        when :no_wildcard_actions
+          <<~RUBY
+            it 'never uses wildcard actions' do
+              policies = result.dig('resource', 'aws_iam_policy') || {}
+              policies.each do |name, config|
+                policy = JSON.parse(config['policy'])
+                policy['Statement'].each do |stmt|
+                  Array(stmt['Action']).each do |action|
+                    expect(action).not_to eq('*'), "Policy \#{name} has wildcard action"
+                  end
+                end
+              end
+            end
+          RUBY
+        when :no_public_ssh
+          <<~RUBY
+            it 'does not allow SSH from 0.0.0.0/0' do
+              sgs = result.dig('resource', 'aws_security_group') || {}
+              sgs.each do |name, config|
+                rules = Array(config['ingress'] || config['ingress_rules'])
+                ssh_rules = rules.select { |r| r['from_port'] == 22 }
+                ssh_rules.each do |rule|
+                  expect(Array(rule['cidr_blocks'])).not_to include('0.0.0.0/0')
+                end
+              end
+            end
+          RUBY
+        when :encrypted_volumes
+          <<~RUBY
+            it 'uses encrypted volumes on all instances' do
+              instances = result.dig('resource', 'aws_instance') || {}
+              instances.each do |name, config|
+                expect(config.dig('root_block_device', 'encrypted')).to eq(true),
+                  "Instance \#{name} must have encrypted root volume"
+              end
+            end
+          RUBY
+        else
+          "# Unknown invariant: #{invariant[:type]}"
+        end
+      end
+
+      def format_hash(hash, depth = 0)
+        return '{}' if hash.empty?
+        pad = '  ' * (depth + 1)
+        inner = hash.map do |k, v|
+          case v
+          when Hash then "#{pad}#{k}: #{format_hash(v, depth + 1)}"
+          when Symbol then "#{pad}#{k}: :#{v}"
+          when String then "#{pad}#{k}: '#{v}'"
+          when Array then "#{pad}#{k}: #{v.inspect}"
+          else "#{pad}#{k}: #{v.inspect}"
+          end
+        end.join(",\n")
+        "{\n#{inner},\n#{'  ' * depth}}"
+      end
+
+      def indent(text, level)
+        prefix = '  ' * level
+        text.lines.map { |line| line.strip.empty? ? line : "#{prefix}#{line}" }.join
+      end
+    end
+  end
+end

data/lib/pangea/testing/assertions.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+# Copyright 2025 The Pangea Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module Pangea
+  module Testing
+    module Assertions
+      def assert_terraform_structure(result, resource_type, resource_name)
+        expect(result).to be_a(Hash)
+        resource_key = result.key?('resource') ? 'resource' : :resource
+        resources = result[resource_key]
+        expect(resources).to be_a(Hash)
+        type_resources = resources[resource_type] || resources[resource_type.to_sym]
+        expect(type_resources).to be_a(Hash)
+        config = type_resources[resource_name] || type_resources[resource_name.to_sym]
+        expect(config).to be_a(Hash)
+        config
+      end
+
+      def assert_resource_reference(ref, expected_type, expected_name, expected_outputs = {})
+        expect(ref).to be_a(Pangea::Resources::ResourceReference)
+        expect(ref.type).to eq(expected_type)
+        expect(ref.name).to eq(expected_name)
+        expected_outputs.each do |key, value|
+          expect(ref.outputs[key]).to eq(value)
+        end
+        ref
+      end
+
+      def assert_tags_present(config, expected_tags)
+        tags = config['tags'] || config[:tags]
+        expect(tags).not_to be_nil
+        expected_tags.each do |key, value|
+          expect(tags[key.to_s] || tags[key.to_sym]).to eq(value)
+        end
+      end
+    end
+  end
+end

data/lib/pangea/testing/mock_terraform_synthesizer.rb

@@ -19,9 +19,16 @@ require_relative 'mock_resource_reference'
 module Pangea
   module Testing
     # Mock synthesizer for testing when TerraformSynthesizer is not available.
-    # Accepts ANY resource method call (aws_, google_, azurerm_, hcloud_, cloudflare_, etc.)
-    # and records the resource in the synthesis output.
+    # Accepts resource method calls matching known provider prefixes (aws_, google_,
+    # azurerm_, hcloud_, cloudflare_, etc.) and records the resource in the synthesis output.
     class MockTerraformSynthesizer
+      # Known Terraform provider resource prefixes
+      VALID_RESOURCE_PREFIXES = %w[
+        aws_ google_ azurerm_ hcloud_ cloudflare_ kubernetes_ helm_
+        null_ random_ local_ tls_ time_ archive_ external_ template_
+        akeyless_ datadog_ splunk_ vault_ consul_ nomad_ digitalocean_
+      ].freeze
+
       attr_reader :resources, :data_sources, :outputs
 
       def initialize
@@ -40,6 +47,11 @@ module Pangea
 
       def method_missing(method_name, *args, &block)
         resource_type = method_name.to_s
+
+        unless valid_resource_type?(resource_type)
+          super
+        end
+
         resource_name = args[0].to_s
         resource_config = args[1] || {}
 
@@ -49,8 +61,14 @@ module Pangea
         MockResourceReference.new(resource_type, resource_name, resource_config)
       end
 
-      def respond_to_missing?(_method_name, _include_private = false)
-        true
+      def respond_to_missing?(method_name, _include_private = false)
+        valid_resource_type?(method_name.to_s) || super
+      end
+
+      private
+
+      def valid_resource_type?(name)
+        VALID_RESOURCE_PREFIXES.any? { |prefix| name.start_with?(prefix) }
       end
     end
   end

data/lib/pangea/testing/spec_generator.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module Pangea
+  module Testing
+    # Auto-generates RSpec synthesis specs from resource metadata.
+    #
+    # Usage:
+    #   generator = SpecGenerator.new(
+    #     provider_module: 'Pangea::Resources::AWS',
+    #     resource_type: 'aws_iam_instance_profile',
+    #     attributes_class: 'Pangea::Resources::AWS::Types::IamInstanceProfileAttributes',
+    #     required_attributes: { name: 'test-profile', role: 'test-role' },
+    #     optional_attributes: { path: '/custom/', tags: { Env: 'test' } },
+    #     expected_outputs: [:id, :arn, :name, :unique_id],
+    #     mutually_exclusive: [[:name, :name_prefix]],
+    #     terraform_ref_fields: [:role, :name],
+    #     supports_tags: true,
+    #   )
+    #   puts generator.generate
+    #
+    class SpecGenerator
+      HEADER = <<~RUBY.freeze
+        # frozen_string_literal: true
+        # Auto-generated by Pangea::Testing::SpecGenerator
+        # Regenerate with: pangea-core spec-gen or forge pangea-spec-gen
+
+        require 'spec_helper'
+      RUBY
+
+      attr_reader :config
+
+      def initialize(**config)
+        @config = config
+        validate_config!
+      end
+
+      def generate
+        [
+          HEADER,
+          describe_block,
+        ].join("\n")
+      end
+
+      private
+
+      def provider_module = config[:provider_module]
+      def resource_type = config[:resource_type]
+      def required_attrs = config[:required_attributes] || {}
+      def optional_attrs = config[:optional_attributes] || {}
+      def expected_outputs = config[:expected_outputs] || [:id]
+      def mutually_exclusive = config[:mutually_exclusive] || []
+      def tf_ref_fields = config[:terraform_ref_fields] || []
+      def supports_tags = config.fetch(:supports_tags, true)
+
+      def describe_block
+        tests = []
+        tests << synthesis_test
+        tests << reference_test
+        tests << tags_test if supports_tags
+        tf_ref_fields.each { |field| tests << terraform_ref_test(field) }
+        mutually_exclusive.each { |pair| tests << mutually_exclusive_test(pair) }
+
+        <<~RUBY
+          RSpec.describe '#{resource_type}' do
+            let(:synthesizer) { TerraformSynthesizer.new }
+
+          #{tests.map { |t| indent(t, 2) }.join("\n\n")}
+          end
+        RUBY
+      end
+
+      def synthesis_test
+        <<~RUBY
+          it 'synthesizes with valid attributes' do
+            synthesizer.instance_eval do
+              extend #{provider_module}
+              #{resource_type}(:test, #{format_hash(required_attrs)})
+            end
+            result = synthesizer.synthesis
+            config = result[:resource][:#{resource_type}][:test]
+            expect(config).to be_a(Hash)
+          end
+        RUBY
+      end
+
+      def reference_test
+        output_assertions = expected_outputs.map do |output|
+          "  expect(ref.outputs[:#{output}]).to eq('${#{resource_type}.test.#{output}}')"
+        end.join("\n")
+
+        <<~RUBY
+          it 'returns ResourceReference with correct outputs' do
+            ref = synthesizer.instance_eval do
+              extend #{provider_module}
+              #{resource_type}(:test, #{format_hash(required_attrs)})
+            end
+            expect(ref).to be_a(Pangea::Resources::ResourceReference)
+            expect(ref.type).to eq('#{resource_type}')
+            expect(ref.name).to eq(:test)
+          #{output_assertions}
+          end
+        RUBY
+      end
+
+      def tags_test
+        tagged = required_attrs.merge(tags: { Environment: 'test', Team: 'platform' })
+        <<~RUBY
+          it 'synthesizes with tags' do
+            synthesizer.instance_eval do
+              extend #{provider_module}
+              #{resource_type}(:test, #{format_hash(tagged)})
+            end
+            result = synthesizer.synthesis
+            config = result[:resource][:#{resource_type}][:test]
+            expect(config[:tags]).to be_a(Hash) if config[:tags]
+          end
+        RUBY
+      end
+
+      def terraform_ref_test(field)
+        ref_attrs = required_attrs.merge(field => '${other.resource.id}')
+        <<~RUBY
+          it 'accepts Terraform references in #{field}' do
+            expect {
+              synthesizer.instance_eval do
+                extend #{provider_module}
+                #{resource_type}(:test, #{format_hash(ref_attrs)})
+              end
+            }.not_to raise_error
+          end
+        RUBY
+      end
+
+      def mutually_exclusive_test(fields)
+        both_set = required_attrs.merge(fields.map { |f| [f, "value-#{f}"] }.to_h)
+        <<~RUBY
+          it 'rejects both #{fields.join(" and ")} set simultaneously' do
+            expect {
+              synthesizer.instance_eval do
+                extend #{provider_module}
+                #{resource_type}(:test, #{format_hash(both_set)})
+              end
+            }.to raise_error(Dry::Struct::Error)
+          end
+        RUBY
+      end
+
+      def format_hash(hash, depth = 0)
+        return '{}' if hash.empty?
+        pad = '  ' * (depth + 1)
+        inner = hash.map do |k, v|
+          case v
+          when Hash then "#{pad}#{k}: #{format_hash(v, depth + 1)}"
+          when Symbol then "#{pad}#{k}: :#{v}"
+          when String then "#{pad}#{k}: '#{v.gsub("'", "\\\\'")}'"
+          when Array then "#{pad}#{k}: #{v.inspect}"
+          when TrueClass, FalseClass, Integer, Float then "#{pad}#{k}: #{v}"
+          else "#{pad}#{k}: #{v.inspect}"
+          end
+        end.join(",\n")
+        "{\n#{inner},\n#{'  ' * depth}}"
+      end
+
+      def indent(text, level)
+        prefix = '  ' * level
+        text.lines.map { |line| line.strip.empty? ? line : "#{prefix}#{line}" }.join
+      end
+
+      def validate_config!
+        raise ArgumentError, ':provider_module is required' unless config[:provider_module]
+        raise ArgumentError, ':resource_type is required' unless config[:resource_type]
+        raise ArgumentError, ':required_attributes is required' unless config[:required_attributes]
+      end
+    end
+  end
+end

data/lib/pangea/testing/spec_setup.rb

@@ -35,6 +35,10 @@ module Pangea
           end
         end
 
+        # Load shared examples (type purity, resource patterns)
+        require_relative 'type_purity'
+        require_relative 'resource_examples'
+
         RSpec.configure do |config|
           config.example_status_persistence_file_path = '.rspec_status'
           config.disable_monkey_patching!

data/lib/pangea/testing/type_purity.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require 'rspec'
+
+module Pangea
+  module Testing
+    # Shared RSpec examples and helpers for proving type purity across
+    # ALL Pangea provider gems. Include in any provider spec to validate:
+    #
+    #   - All types inherit BaseAttributes (not Dry::Struct)
+    #   - No T::Ref unions in generated types
+    #   - ResourceInput handles refs at the serialization boundary
+    #   - Literal values are validated strictly per-field
+    #   - Required coverage enforced for ref-carrying fields
+    #
+    # Usage:
+    #   RSpec.describe 'pangea-porkbun type purity' do
+    #     it_behaves_like 'a pure typed provider',
+    #       provider_module: Pangea::Resources::Porkbun,
+    #       types_module: Pangea::Resources::Porkbun::Types,
+    #       lib_path: File.expand_path('../../lib', __dir__)
+    #   end
+    #
+    module TypePurity
+      # ── Helper: scan a provider's lib/ for type violations ────────
+
+      # Scan all types.rb files under a path and return violations.
+      # @param lib_path [String] Absolute path to the provider's lib/ directory
+      # @return [Hash] { base_attributes: [paths], dry_struct: [paths], ref_unions: [paths] }
+      def self.audit_types(lib_path)
+        types_files = Dir.glob(File.join(lib_path, '**', 'types.rb'))
+        result = { base_attributes: [], dry_struct: [], ref_unions: [] }
+
+        types_files.each do |f|
+          content = File.read(f)
+          rel = f.sub("#{lib_path}/", '')
+
+          if content.include?('< Pangea::Resources::BaseAttributes')
+            result[:base_attributes] << rel
+          elsif content.include?('< Dry::Struct')
+            result[:dry_struct] << rel
+          end
+
+          if content.match?(/\| T::Ref\b/)
+            result[:ref_unions] << rel
+          end
+        end
+
+        result
+      end
+
+      # ── Helper: collect all attribute classes from a Types module ──
+
+      # Find all Dry::Struct subclasses in a types module.
+      # @param types_module [Module] e.g. Pangea::Resources::Porkbun::Types
+      # @return [Array<Class>] Attribute classes
+      def self.attribute_classes(types_module)
+        types_module.constants(false)
+          .map { |c| types_module.const_get(c) }
+          .select { |c| c.is_a?(Class) && c < Dry::Struct }
+      end
+
+      # ── Shared Examples ───────────────────────────────────────────
+
+      RSpec.shared_examples 'a pure typed provider' do |provider_module:, types_module:, lib_path:|
+        describe 'type purity' do
+          let(:audit) { TypePurity.audit_types(lib_path) }
+          let(:attr_classes) { TypePurity.attribute_classes(types_module) }
+
+          it 'has NO Dry::Struct inheritance (all types use BaseAttributes)' do
+            expect(audit[:dry_struct]).to be_empty,
+              "#{audit[:dry_struct].length} types still inherit Dry::Struct:\n" \
+              "#{audit[:dry_struct].join("\n")}"
+          end
+
+          it 'has at least one BaseAttributes type' do
+            expect(audit[:base_attributes]).not_to be_empty,
+              'No BaseAttributes types found — provider may not be generated'
+          end
+
+          it 'has NO T::Ref union types (refs handled at serialization boundary)' do
+            expect(audit[:ref_unions]).to be_empty,
+              "#{audit[:ref_unions].length} types contain | T::Ref unions:\n" \
+              "#{audit[:ref_unions].join("\n")}"
+          end
+
+          it 'all attribute classes inherit BaseAttributes' do
+            non_base = attr_classes.reject { |c| c < Pangea::Resources::BaseAttributes }
+            expect(non_base).to be_empty,
+              "#{non_base.length} classes don't inherit BaseAttributes: #{non_base.map(&:name).join(', ')}"
+          end
+        end
+      end
+
+      # ── Shared Examples: ResourceInput integration ────────────────
+
+      RSpec.shared_examples 'ResourceInput handles refs for' do |attributes_class:, literal_attrs:, ref_attr:, ref_value: '${aws_test.x.id}'|
+        describe "ResourceInput with #{attributes_class}" do
+          let(:all_attrs) { literal_attrs.merge(ref_attr => ref_value) }
+          let(:input) { Pangea::Resources::ResourceInput.partition(attributes_class, all_attrs) }
+
+          it 'partitions ref from literals' do
+            expect(input.refs).to have_key(ref_attr)
+            expect(input.refs[ref_attr]).to eq(ref_value)
+          end
+
+          it 'validates literals strictly' do
+            input # should not raise
+            literal_attrs.each do |k, _v|
+              expect(input.validated.to_h).to have_key(k)
+            end
+          end
+
+          it '[] resolves ref over literal' do
+            expect(input[ref_attr]).to eq(ref_value)
+          end
+
+          it 'to_h includes both literals and refs' do
+            h = input.to_h
+            literal_attrs.each { |k, v| expect(h[k]).to eq(v) }
+            expect(h[ref_attr]).to eq(ref_value)
+          end
+
+          it 'is frozen' do
+            expect(input).to be_frozen
+            expect(input.refs).to be_frozen
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pangea/testing.rb

@@ -19,4 +19,7 @@ require_relative 'testing/mock_resource_reference'
 require_relative 'testing/mock_terraform_synthesizer'
 require_relative 'testing/synthesis_test_helpers'
 require_relative 'testing/resource_examples'
+require_relative 'testing/type_purity'
 require_relative 'testing/spec_setup'
+require_relative 'testing/spec_generator'
+require_relative 'testing/architecture_spec_generator'