pangea-core 0.1.0 → 0.3.0

data/lib/pangea/tagging/policy.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Pangea
+  module Tagging
+    # Enforces tagging policies across all resources in an architecture.
+    #
+    # Usage:
+    #   policy = TaggingPolicy.new(
+    #     required_keys: %w[ManagedBy Purpose Environment Team Cluster PangeaFingerprint],
+    #     forbidden_values: { ManagedBy: ['manual', 'unknown'] },
+    #   )
+    #   policy.validate!(resource_tags) # raises on violation
+    #   policy.compliant?(resource_tags) # returns boolean
+    #
+    class TaggingPolicy
+      attr_reader :required_keys, :forbidden_values, :max_tag_count
+
+      def initialize(required_keys: [], forbidden_values: {}, max_tag_count: 50)
+        @required_keys = required_keys.map(&:to_s).freeze
+        @forbidden_values = forbidden_values.transform_keys(&:to_s).freeze
+        @max_tag_count = max_tag_count
+      end
+
+      # Validate tags, raising on violation
+      def validate!(tags, resource_name: 'unknown')
+        violations = check(tags)
+        return if violations.empty?
+
+        msg = violations.map { |v| "  - #{v}" }.join("\n")
+        raise TaggingViolation, "Resource '#{resource_name}' tagging violations:\n#{msg}"
+      end
+
+      # Check compliance without raising
+      def compliant?(tags)
+        check(tags).empty?
+      end
+
+      # Return list of violations (empty = compliant)
+      def check(tags)
+        tag_hash = normalize_tags(tags)
+        violations = []
+
+        required_keys.each do |key|
+          unless tag_hash.key?(key)
+            violations << "Missing required tag: #{key}"
+          end
+        end
+
+        forbidden_values.each do |key, forbidden|
+          if tag_hash.key?(key) && forbidden.include?(tag_hash[key])
+            violations << "Forbidden value '#{tag_hash[key]}' for tag '#{key}'"
+          end
+        end
+
+        if tag_hash.length > max_tag_count
+          violations << "Too many tags: #{tag_hash.length} (max: #{max_tag_count})"
+        end
+
+        violations
+      end
+
+      # Default policy for Pangea-managed infrastructure
+      def self.default
+        new(
+          required_keys: %w[ManagedBy Purpose Environment Team PangeaFingerprint],
+          forbidden_values: {
+            'ManagedBy' => %w[manual unknown],
+            'Environment' => %w[],
+          },
+        )
+      end
+
+      # Strict policy with cluster identification
+      def self.strict
+        new(
+          required_keys: %w[ManagedBy Purpose Environment Team Cluster PangeaFingerprint PangeaFingerprintFull PangeaArchitecture],
+          forbidden_values: {
+            'ManagedBy' => %w[manual unknown terraform],
+          },
+        )
+      end
+
+      private
+
+      def normalize_tags(tags)
+        tags.transform_keys(&:to_s)
+      end
+    end
+
+    class TaggingViolation < StandardError; end
+  end
+end

data/lib/pangea/tagging/tag_adapter.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Pangea
+  module Tagging
+    # Registry mapping Terraform resource type prefixes to tag transform methods.
+    #
+    # When a resource is synthesized, the adapter automatically selects the
+    # correct format based on the resource type. Patterns are checked in order
+    # -- first match wins -- so specific patterns (e.g. aws_autoscaling_group)
+    # must appear before general ones (e.g. aws_*).
+    #
+    # Usage:
+    #   TagAdapter.format_for(:aws_vpc)
+    #   # => { pattern: /^aws_/, method: :to_aws, attr: :tags }
+    #
+    #   TagAdapter.transform(tag_set, :google_compute_instance)
+    #   # => { labels: { "managedby" => "pangea", ... } }
+    #
+    class TagAdapter
+      # Registry mapping resource type patterns to tag format methods.
+      # Checked in order -- first match wins.
+      FORMATS = [
+        # AWS ASG uses block-based tags (singular `tag`)
+        { pattern: /^aws_autoscaling_group$/, method: :to_aws_asg, attr: :tag },
+
+        # AWS Launch Template uses nested tag_specifications
+        { pattern: /^aws_launch_template$/, method: :to_aws_tag_spec, attr: :tag_specifications },
+
+        # AWS (default) -- simple map tags
+        { pattern: /^aws_/, method: :to_aws, attr: :tags },
+
+        # Azure -- same as AWS
+        { pattern: /^azurerm_/, method: :to_azure, attr: :tags },
+
+        # GCP -- lowercase labels
+        { pattern: /^google_/, method: :to_gcp, attr: :labels },
+
+        # Hcloud -- lowercase labels
+        { pattern: /^hcloud_/, method: :to_hcloud, attr: :labels },
+
+        # Kubernetes -- labels (not annotations)
+        { pattern: /^kubernetes_/, method: :to_kubernetes, attr: :labels },
+
+        # Datadog -- array of "key:value" strings
+        { pattern: /^datadog_/, method: :to_datadog, attr: :tags },
+
+        # Cloudflare -- array of "key:value" strings
+        { pattern: /^cloudflare_/, method: :to_cloudflare, attr: :tags },
+
+        # Vault -- array strings
+        { pattern: /^vault_/, method: :to_vault, attr: :tags },
+
+        # MongoDBAtlas -- array of {key, value}
+        { pattern: /^mongodbatlas_/, method: :to_mongodbatlas, attr: :tags },
+
+        # Consul -- simple map
+        { pattern: /^consul_/, method: :to_consul, attr: :tags },
+
+        # Nomad -- lowercase labels
+        { pattern: /^nomad_/, method: :to_nomad, attr: :meta },
+
+        # Default fallback -- simple map
+        { pattern: /.*/, method: :to_aws, attr: :tags },
+      ].freeze
+
+      # Look up the correct tag format for a resource type.
+      # Returns { pattern:, method:, attr: } or nil.
+      def self.format_for(resource_type)
+        resource_type_str = resource_type.to_s
+        FORMATS.find { |f| f[:pattern].match?(resource_type_str) }
+      end
+
+      # Transform a TagSet for a specific resource type.
+      # Returns { attribute_name => transformed_value }
+      def self.transform(tag_set, resource_type)
+        fmt = format_for(resource_type)
+        return {} unless fmt && tag_set
+
+        value = tag_set.send(fmt[:method])
+        { fmt[:attr] => value }
+      end
+    end
+  end
+end

data/lib/pangea/tagging/tag_set.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+module Pangea
+  module Tagging
+    # A canonical tag set with provider-specific format transformations.
+    #
+    # Wraps a Hash of symbol-keyed tags and provides methods to convert
+    # to every provider's expected tag/label format. Tags are defined once
+    # and transformed at the point of use.
+    #
+    # Usage:
+    #   tags = TagSet.new(ManagedBy: 'pangea', Team: 'platform', Name: 'my-vpc')
+    #   tags.merge(Environment: 'dev')
+    #
+    #   # AWS resources (simple map)
+    #   ctx.aws_vpc(:vpc, tags: tags.to_aws)
+    #
+    #   # AWS ASG (block-based tags with propagation)
+    #   ctx.aws_autoscaling_group(:asg, tag: tags.to_aws_asg)
+    #
+    #   # AWS Launch Template (nested tag_specifications)
+    #   ctx.aws_launch_template(:lt, tag_specifications: tags.to_aws_tag_spec)
+    #
+    #   # GCP / Hcloud (lowercase label keys)
+    #   ctx.google_compute_instance(:vm, labels: tags.to_gcp)
+    #   ctx.hcloud_server(:srv, labels: tags.to_hcloud)
+    #
+    #   # Azure (same as AWS)
+    #   ctx.azurerm_resource_group(:rg, tags: tags.to_azure)
+    #
+    class TagSet
+      attr_reader :entries
+
+      def initialize(tags = {})
+        @entries = tags.each_with_object({}) do |(k, v), h|
+          h[k.to_sym] = v.to_s
+        end.freeze
+      end
+
+      # Create a new TagSet with additional tags merged in.
+      # Does not mutate the original.
+      def merge(extra = {})
+        self.class.new(@entries.merge(extra))
+      end
+
+      # ── AWS Formats ──────────────────────────────────────────────
+
+      # Simple AWS tags map: { "Key" => "value" }
+      # Used by: aws_vpc, aws_subnet, aws_security_group, aws_lb, aws_iam_role, aws_s3_bucket, etc.
+      def to_aws
+        @entries.transform_keys(&:to_s)
+      end
+
+      # AWS ASG tags: [{ key: "K", value: "V", propagate_at_launch: true }, ...]
+      # Used by: aws_autoscaling_group `tag` attribute
+      def to_aws_asg(propagate: true)
+        @entries.map { |k, v| { key: k.to_s, value: v.to_s, propagate_at_launch: propagate } }
+      end
+
+      # AWS Launch Template tag_specifications:
+      # [{ resource_type: "instance", tags: { "Key" => "value" } }]
+      # Used by: aws_launch_template inside `tag_specifications` attribute
+      def to_aws_tag_spec(resource_type: 'instance')
+        [{ resource_type: resource_type, tags: to_aws }]
+      end
+
+      # ── GCP Format ─────────────────────────────────────────────
+
+      # GCP labels: lowercase keys, only [a-z0-9_-], max 63 chars.
+      # Values also lowercased and sanitized.
+      # Used by: google_compute_*, google_container_cluster, etc.
+      def to_gcp
+        @entries.each_with_object({}) do |(k, v), h|
+          key = sanitize_label(k.to_s)
+          val = sanitize_label(v.to_s)
+          h[key] = val
+        end
+      end
+
+      # ── Azure Format ───────────────────────────────────────────
+
+      # Azure tags: same format as AWS (string key-value map)
+      # Used by: azurerm_resource_group, azurerm_kubernetes_cluster, etc.
+      def to_azure
+        to_aws
+      end
+
+      # ── Hcloud Format ──────────────────────────────────────────
+
+      # Hcloud labels: same format as GCP (lowercase, sanitized)
+      # Used by: hcloud_server, hcloud_network, etc.
+      def to_hcloud
+        to_gcp
+      end
+
+      # ── Kubernetes Format ─────────────────────────────────────
+      # Kubernetes labels: lowercase keys with optional prefix (e.g., "app.kubernetes.io/name")
+      # Same sanitization as GCP but allows "/" and "." in keys
+      def to_kubernetes
+        @entries.each_with_object({}) do |(k, v), h|
+          key = k.to_s.downcase.gsub(/[^a-z0-9_.\/\-]/, '-')
+          val = v.to_s
+          h[key] = val
+        end
+      end
+
+      # Kubernetes annotations: arbitrary key-value (no sanitization needed)
+      def to_kubernetes_annotations
+        @entries.transform_keys(&:to_s)
+      end
+
+      # ── Cloudflare Format ──────────────────────────────────────
+
+      # Cloudflare tags: array of "key:value" strings
+      # Used by: cloudflare_record (tags attribute is an array of strings)
+      def to_cloudflare
+        @entries.map { |k, v| "#{k}:#{v}" }
+      end
+
+      # ── Datadog Format ─────────────────────────────────────────
+
+      # Datadog tags: array of "key:value" strings
+      # Used by: datadog_monitor, datadog_dashboard, etc.
+      def to_datadog
+        @entries.map { |k, v| "#{k}:#{v}" }
+      end
+
+      # ── Vault Format ──────────────────────────────────────────
+      # Vault tags: array of "key:value" strings
+      def to_vault
+        @entries.map { |k, v| "#{k}:#{v}" }
+      end
+
+      # ── MongoDBAtlas Format ────────────────────────────────────
+      # MongoDB Atlas tags: array of {key: "K", value: "V"} objects
+      def to_mongodbatlas
+        @entries.map { |k, v| { key: k.to_s, value: v.to_s } }
+      end
+
+      # ── GitHub Format ─────────────────────────────────────────
+      # GitHub labels: simple string array (just the keys, no values)
+      def to_github_labels
+        @entries.keys.map(&:to_s)
+      end
+
+      # ── Consul Format ─────────────────────────────────────────
+      # Consul: simple map like AWS
+      def to_consul
+        to_aws
+      end
+
+      # ── Nomad Format ──────────────────────────────────────────
+      # Nomad: uses "meta" block with lowercase keys
+      def to_nomad
+        to_gcp
+      end
+
+      # ── Auto-format Detection ─────────────────────────────────
+
+      # Transform for a specific resource type (auto-detect format).
+      # Returns { attribute_name => transformed_value }
+      def for_resource(resource_type)
+        TagAdapter.transform(self, resource_type)
+      end
+
+      # ── Raw Access ─────────────────────────────────────────────
+
+      # Hash-style access for backward compatibility
+      def [](key)
+        @entries[key.to_sym]
+      end
+
+      def key?(key)
+        @entries.key?(key.to_sym)
+      end
+
+      def to_h
+        @entries.dup
+      end
+
+      def to_s
+        "TagSet(#{@entries.length} tags)"
+      end
+
+      def inspect
+        "TagSet(#{@entries.inspect})"
+      end
+
+      # Iterate over entries
+      def each(&block)
+        @entries.each(&block)
+      end
+
+      private
+
+      def sanitize_label(str)
+        str.downcase.gsub(/[^a-z0-9_-]/, '_')[0, 63]
+      end
+    end
+  end
+end

data/lib/pangea/tagging.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative 'tagging/fingerprint'
+require_relative 'tagging/policy'
+require_relative 'tagging/tag_adapter'
+require_relative 'tagging/tag_set'

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