pangea-core 0.1.0 → 0.3.0

data/lib/pangea/entities/module_definition.rb

@@ -0,0 +1,120 @@
+# 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.
+
+require 'dry-struct'
+
+module Pangea
+  module Entities
+    class ModuleDefinition < Dry::Struct
+      module Type
+        RESOURCE = :resource
+        FUNCTION = :function
+        COMPOSITE = :composite
+      end
+
+      attribute :name, Pangea::Types::ModuleName
+      attribute :version, Pangea::Types::Version.optional.default("0.0.1")
+      attribute :description, Pangea::Types::OptionalString.default(nil)
+      attribute :author, Pangea::Types::OptionalString.default(nil)
+
+      attribute :type, Pangea::Types::Strict::Symbol.default(:resource).enum(:resource, :function, :composite)
+      attribute :source, Pangea::Types::FilePath.optional.default(nil)
+      attribute :path, Pangea::Types::DirectoryPath.optional.default(nil)
+
+      attribute :inputs, Pangea::Types::SymbolizedHash.default({}.freeze)
+      attribute :outputs, Pangea::Types::SymbolizedHash.default({}.freeze)
+      attribute :dependencies, Pangea::Types::ModuleArray.default([].freeze)
+
+      attribute :ruby_version, Pangea::Types::Version.optional.default(nil)
+      attribute :required_gems, Pangea::Types::SymbolizedHash.default({}.freeze)
+
+      def resource_module?
+        type == Type::RESOURCE || type == Type::COMPOSITE
+      end
+
+      def function_module?
+        type == Type::FUNCTION || type == Type::COMPOSITE
+      end
+
+      def load_path
+        return path if path
+        return File.dirname(source) if source
+
+        "modules/#{name}"
+      end
+
+      def required_inputs
+        inputs.select { |_, config| config[:required] }.keys
+      end
+
+      def optional_inputs
+        inputs.reject { |_, config| config[:required] }.keys
+      end
+
+      def validate_inputs(provided_inputs)
+        errors = []
+        provided = provided_inputs.keys.map(&:to_sym)
+
+        required_inputs.each do |input|
+          unless provided.include?(input)
+            errors << "Missing required input: #{input}"
+          end
+        end
+
+        provided.each do |input|
+          unless inputs.key?(input)
+            errors << "Unknown input: #{input}"
+          end
+        end
+
+        provided_inputs.each do |key, value|
+          if inputs[key.to_sym] && inputs[key.to_sym][:type]
+            expected_type = inputs[key.to_sym][:type]
+          end
+        end
+
+        raise ValidationError, errors.join(", ") unless errors.empty?
+        true
+      end
+
+      def to_documentation
+        doc = ["# Module: #{name}"]
+        doc << "Version: #{version}" if version
+        doc << "\n#{description}" if description
+        doc << "\nAuthor: #{author}" if author
+
+        if inputs.any?
+          doc << "\n## Inputs"
+          inputs.each do |name, config|
+            required = config[:required] ? " (required)" : ""
+            doc << "- `#{name}`#{required}: #{config[:description] || 'No description'}"
+            doc << "  - Type: #{config[:type]}" if config[:type]
+            doc << "  - Default: #{config[:default]}" if config[:default]
+          end
+        end
+
+        if outputs.any?
+          doc << "\n## Outputs"
+          outputs.each do |name, config|
+            doc << "- `#{name}`: #{config[:description] || 'No description'}"
+          end
+        end
+
+        doc.join("\n")
+      end
+    end
+  end
+end

data/lib/pangea/entities/namespace.rb

@@ -0,0 +1,144 @@
+# 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.
+
+require 'dry-struct'
+
+module Pangea
+  module Entities
+    class Namespace < Dry::Struct
+      class StateConfig < Dry::Struct
+        attribute? :bucket, Pangea::Types::String
+        attribute? :key, Pangea::Types::String
+        attribute? :region, Pangea::Types::String.optional
+        attribute? :dynamodb_table, Pangea::Types::String
+        attribute? :lock, Pangea::Types::String
+        attribute? :encrypt, Pangea::Types::Bool
+        attribute? :path, Pangea::Types::String
+
+        def validate_s3!
+          errors = []
+          errors << "S3 bucket name is required" if bucket.nil?
+          errors << "S3 key is required" if key.nil?
+          lock_table = dynamodb_table || lock
+          errors << "DynamoDB lock table is required" if lock_table.nil?
+          raise ::Pangea::Entities::ValidationError, errors.join(", ") unless errors.empty?
+        end
+
+        def lock_table
+          dynamodb_table || lock
+        end
+      end
+
+      class State < Dry::Struct
+        attribute :type, Pangea::Types::StateBackendType
+        attribute :config, StateConfig
+
+        def self.new(attributes)
+          attrs = attributes.is_a?(Hash) ? attributes : {}
+          state_type = attrs[:type]
+          config_attrs = attrs[:config] || {}
+
+          if state_type == :s3
+            required_fields = [:bucket, :key]
+            missing_fields = required_fields.select { |field| config_attrs[field].nil? || config_attrs[field].empty? }
+            unless missing_fields.empty?
+              raise ::Pangea::Entities::ValidationError, "S3 backend requires: #{missing_fields.join(', ')}"
+            end
+          elsif state_type == :local
+            config_attrs[:path] ||= "./terraform.tfstate"
+          end
+
+          super(attrs)
+        end
+
+        def s3?
+          type == :s3
+        end
+
+        def local?
+          type == :local
+        end
+      end
+
+      attribute :name, Pangea::Types::NamespaceString
+      attribute :state, State
+      attribute :description, Pangea::Types::OptionalString.default(nil)
+      attribute :tags, Pangea::Types::SymbolizedHash.default({}.freeze)
+
+      def s3_backend?
+        state.s3?
+      end
+
+      def local_backend?
+        state.local?
+      end
+
+      def state_config
+        config = {
+          type: state.type,
+          region: state.config.region
+        }
+
+        if s3_backend?
+          config[:bucket] = state.config.bucket
+          config[:lock] = state.config.lock
+        end
+
+        config.compact
+      end
+
+      def s3_config
+        raise "Namespace #{name} does not use S3 backend" unless s3_backend?
+        state.config.validate_s3!
+        {
+          bucket: state.config.bucket,
+          key: state.config.key,
+          region: state.config.region,
+          dynamodb_table: state.config.lock_table
+        }
+      end
+
+      def to_terraform_backend
+        if local_backend?
+          return {
+            local: {
+              path: state.config.path || "terraform.tfstate"
+            }
+          }
+        end
+
+        if state.config.bucket.nil? || state.config.bucket.empty?
+          raise ValidationError, "S3 bucket is required but was nil or empty for namespace '#{name}'"
+        end
+        if state.config.key.nil? || state.config.key.empty?
+          raise ValidationError, "S3 key is required but was nil or empty for namespace '#{name}'"
+        end
+
+        {
+          s3: {
+            bucket: state.config.bucket,
+            key: state.config.key,
+            region: state.config.region,
+            dynamodb_table: state.config.lock_table,
+            encrypt: state.config.encrypt
+          }.compact
+        }
+      end
+    end
+
+    class ValidationError < StandardError; end
+  end
+end

data/lib/pangea/entities/project.rb

@@ -0,0 +1,84 @@
+# 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.
+
+require 'dry-struct'
+
+module Pangea
+  module Entities
+    class Project < Dry::Struct
+      attribute :name, Pangea::Types::ProjectString
+      attribute :namespace, Pangea::Types::NamespaceString
+      attribute :site, Pangea::Types::SiteString.optional.default(nil)
+      attribute :description, Pangea::Types::OptionalString.default(nil)
+
+      attribute :modules, Pangea::Types::ModuleArray.default([].freeze)
+      attribute :variables, Pangea::Types::SymbolizedHash.default({}.freeze)
+      attribute :outputs, Pangea::Types::StringArray.default([].freeze)
+      attribute :depends_on, Pangea::Types::IdentifierArray.default([].freeze)
+
+      attribute :terraform_version, Pangea::Types::TerraformVersion.optional.default(nil)
+      attribute :tags, Pangea::Types::SymbolizedHash.default({}.freeze)
+
+      def full_name
+        [namespace, site, name].compact.join('.')
+      end
+
+      def state_key
+        parts = [namespace]
+        parts << site if site
+        parts << name
+        parts.join('/')
+      end
+
+      def has_modules?
+        !modules.empty?
+      end
+
+      def has_dependencies?
+        !depends_on.empty?
+      end
+
+      def module_config(module_name)
+        modules.find { |m| m == module_name }
+      end
+
+      def to_backend_config(prefix: nil)
+        key_parts = [prefix, state_key].compact
+        {
+          key: key_parts.join('/'),
+          workspace_key_prefix: "workspaces"
+        }
+      end
+
+      def validate!
+        errors = []
+
+        if depends_on.include?(name)
+          errors << "Project cannot depend on itself"
+        end
+
+        modules.each do |mod|
+          unless mod.match?(/\A[a-z][a-z0-9_-]*\z/)
+            errors << "Invalid module name: #{mod}"
+          end
+        end
+
+        raise ValidationError, errors.join(", ") unless errors.empty?
+        true
+      end
+    end
+  end
+end

data/lib/pangea/entities/template.rb

@@ -0,0 +1,103 @@
+# 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.
+
+require 'dry-struct'
+
+module Pangea
+  module Entities
+    class Template < Dry::Struct
+      attribute :name, Pangea::Types::Identifier
+      attribute :content, Pangea::Types::Strict::String
+      attribute :file_path, Pangea::Types::FilePath.optional.default(nil)
+
+      attribute :namespace, Pangea::Types::NamespaceString.optional.default(nil)
+      attribute :project, Pangea::Types::ProjectString.optional.default(nil)
+      attribute :variables, Pangea::Types::SymbolizedHash.default({}.freeze)
+
+      attribute :target_version, Pangea::Types::TerraformVersion.optional.default(nil)
+      attribute :strict_mode, Pangea::Types::Strict::Bool.default(false)
+
+      def source
+        file_path || "<inline:#{name}>"
+      end
+
+      def from_file?
+        !file_path.nil?
+      end
+
+      def cache_key
+        parts = [namespace, project, name].compact
+        parts.join('/')
+      end
+
+      def validate!
+        errors = []
+
+        if content.strip.empty?
+          errors << "Template content cannot be empty"
+        end
+
+        if content.include?("<%") || content.include?("{{")
+          errors << "Template appears to contain ERB or Mustache syntax (not supported)"
+        end
+
+        raise ValidationError, errors.join(", ") unless errors.empty?
+        true
+      end
+
+      def metadata
+        return {} unless content.start_with?("# @")
+
+        metadata = {}
+        content.lines.each do |line|
+          break unless line.start_with?("# @")
+
+          if line =~ /# @(\w+):\s*(.+)$/
+            key = $1.to_sym
+            value = $2.strip
+            metadata[key] = value
+          end
+        end
+
+        metadata
+      end
+
+      def content_without_metadata
+        return content unless content.start_with?("# @")
+
+        lines = content.lines
+        lines.drop_while { |line| line.start_with?("# @") }.join
+      end
+    end
+
+    class CompilationResult < Dry::Struct
+      attribute :success, Pangea::Types::Strict::Bool
+      attribute :terraform_json, Pangea::Types::Strict::String.optional.default(nil)
+      attribute :errors, Pangea::Types::StringArray.default([].freeze)
+      attribute :warnings, Pangea::Types::StringArray.default([].freeze)
+      attribute :template_name, Pangea::Types::Strict::String.optional.default(nil)
+      attribute :template_count, Pangea::Types::Strict::Integer.optional.default(nil)
+
+      def success?
+        success && errors.empty?
+      end
+
+      def failure?
+        !success?
+      end
+    end
+  end
+end

data/lib/pangea/entities.rb

@@ -0,0 +1,26 @@
+# 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.
+
+require_relative 'entities/namespace'
+require_relative 'entities/project'
+require_relative 'entities/module_definition'
+require_relative 'entities/template'
+
+module Pangea
+  module Entities
+    class ValidationError < StandardError; end
+  end
+end

data/lib/pangea/errors.rb

@@ -0,0 +1,124 @@
+# 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 Errors
+    class PangeaError < StandardError
+      attr_reader :context, :cause_chain, :timestamp
+
+      def initialize(message, context: {}, cause: nil)
+        super(message)
+        @context = context
+        @cause_chain = build_cause_chain(cause || self.cause)
+        @timestamp = Time.now
+      end
+
+      def detailed_message
+        lines = ["[#{@timestamp.iso8601}] #{self.class.name}: #{message}"]
+        lines << "Context: #{format_context}" if @context.any?
+        lines << "Cause chain:\n#{format_cause_chain}" if @cause_chain.any?
+        lines.join("\n")
+      end
+
+      def to_h
+        {
+          error_type: self.class.name,
+          message: message,
+          context: @context,
+          cause_chain: @cause_chain,
+          timestamp: @timestamp.iso8601
+        }
+      end
+
+      private
+
+      def build_cause_chain(initial_cause)
+        chain = []
+        current = initial_cause
+        depth = 0
+
+        while current && depth < 10
+          chain << {
+            type: current.class.name,
+            message: current.message,
+            backtrace: current.backtrace&.first(3)
+          }
+          current = current.respond_to?(:cause) ? current.cause : nil
+          depth += 1
+        end
+
+        chain
+      end
+
+      def format_context
+        @context.map { |k, v| "  #{k}: #{v}" }.join("\n")
+      end
+
+      def format_cause_chain
+        @cause_chain.map.with_index do |error, index|
+          indent = "  " * (index + 1)
+          "#{indent}→ #{error[:type]}: #{error[:message]}"
+        end.join("\n")
+      end
+    end
+
+    class ValidationError < PangeaError
+      def self.invalid_attribute(resource, attribute, value, expected)
+        new("#{resource}: Invalid #{attribute} '#{value}'. Expected: #{expected}",
+            context: { resource: resource, attribute: attribute, value: value, expected: expected })
+      end
+
+      def self.missing_required(resource, attribute)
+        new("#{resource}: Missing required attribute '#{attribute}'",
+            context: { resource: resource, attribute: attribute })
+      end
+
+      def self.invalid_reference(source, target, reason)
+        new("Invalid reference from #{source} to #{target}. Reason: #{reason}",
+            context: { source: source, target: target, reason: reason })
+      end
+
+      def self.invalid_type(resource, attribute, expected_type, actual_type)
+        new("#{resource}: Invalid type for '#{attribute}'. Expected: #{expected_type}, Got: #{actual_type}",
+            context: { resource: resource, attribute: attribute, expected_type: expected_type, actual_type: actual_type })
+      end
+
+      def self.out_of_range(resource, attribute, value, range)
+        new("#{resource}: Value '#{value}' for '#{attribute}' is out of range. Expected: #{range}",
+            context: { resource: resource, attribute: attribute, value: value, range: range })
+      end
+    end
+
+    class SynthesisError < PangeaError
+      def self.invalid_template(template_name, reason)
+        new("Failed to synthesize template '#{template_name}': #{reason}",
+            context: { template_name: template_name, reason: reason })
+      end
+
+      def self.circular_dependency(resource1, resource2)
+        new("Circular dependency detected between #{resource1} and #{resource2}",
+            context: { resource1: resource1, resource2: resource2 })
+      end
+    end
+
+    class ResourceNotFoundError < PangeaError
+      def self.new(resource_type, resource_name)
+        super("Resource not found: #{resource_type}.#{resource_name}",
+              context: { resource_type: resource_type, resource_name: resource_name })
+      end
+    end
+  end
+end

data/lib/pangea/logging/formatters.rb

@@ -0,0 +1,90 @@
+# 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.
+
+require 'json'
+require 'time'
+
+module Pangea
+  module Logging
+    module Formatters
+      LEVEL_ROLES = {
+        debug: :debug,
+        info: :info,
+        warn: :warning,
+        error: :error,
+        fatal: :replace
+      }.freeze
+
+      EXCLUDED_CONTEXT_KEYS = %i[
+        timestamp level message correlation_id pid thread_id ruby_version
+      ].freeze
+
+      def format_pretty(entry)
+        timestamp = Time.parse(entry[:timestamp]).strftime('%Y-%m-%d %H:%M:%S.%L')
+        level = entry[:level].ljust(5)
+        level_role = LEVEL_ROLES[entry[:level].downcase.to_sym]
+
+        context_str = build_context_string(entry)
+
+        if defined?(Boreal) && level_role
+          level = Boreal.paint(level, level_role)
+        end
+
+        "#{timestamp} [#{level}] #{entry[:message]}#{context_str}"
+      end
+
+      def format_json(entry)
+        JSON.generate(entry)
+      end
+
+      def format_logfmt(entry)
+        entry.map { |k, v|
+          value = v.to_s.include?(' ') ? "\"#{v}\"" : v
+          "#{k}=#{value}"
+        }.join(' ')
+      end
+
+      def format_simple(entry)
+        "#{entry[:level]} - #{entry[:message]}"
+      end
+
+      private
+
+      def build_context_string(entry)
+        context_items = entry.reject { |k, _| EXCLUDED_CONTEXT_KEYS.include?(k) }
+
+        if context_items.any?
+          " | " + context_items.map { |k, v| "#{k}=#{format_value(v)}" }.join(' ')
+        else
+          ""
+        end
+      end
+
+      def format_value(value)
+        case value
+        when String
+          value.include?(' ') ? "\"#{value}\"" : value
+        when Hash
+          "{#{value.size} items}"
+        when Array
+          "[#{value.size} items]"
+        else
+          value.to_s
+        end
+      end
+    end
+  end
+end