ruby-rego 0.1.0

data/lib/ruby/rego/environment/overrides.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "../value"
+
+module Ruby
+  module Rego
+    # Provides temporary input/data overrides for the environment.
+    module EnvironmentOverrides
+      UNSET = Object.new.freeze
+
+      # @param input [Object]
+      # @param data [Object]
+      # @yieldparam environment [Environment]
+      # @return [Object]
+      def with_overrides(input: UNSET, data: UNSET)
+        original = [@input, @data]
+        memoization.with_context do
+          apply_overrides(input, data)
+          yield self
+        end
+      ensure
+        @input, @data = original
+      end
+
+      private
+
+      def apply_overrides(input, data)
+        @input = Value.from_ruby(input) unless input.equal?(UNSET)
+        @data = Value.from_ruby(data) unless data.equal?(UNSET)
+      end
+    end
+  end
+end

data/lib/ruby/rego/environment/reference_resolution.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require_relative "../ast"
+require_relative "../value"
+
+module Ruby
+  module Rego
+    # Reference resolution helpers for Environment.
+    module EnvironmentReferenceResolution
+      # @param ref [Object]
+      # @return [Value]
+      # :reek:FeatureEnvy
+      def resolve_reference(ref)
+        base, path = if ref.is_a?(AST::Reference)
+                       [ref.base, ref.path]
+                     else
+                       path = [] # @type var path: Array[AST::RefArg]
+                       [ref, path]
+                     end
+        resolve_reference_path(resolve_base(base), path)
+      end
+
+      # @param variable [AST::Variable]
+      # @return [Object]
+      def reference_key_for(variable)
+        resolve_reference_variable(variable)
+      end
+
+      private
+
+      # :reek:TooManyStatements
+      # :reek:FeatureEnvy
+      def resolve_base(base)
+        return lookup(base.name) if base.is_a?(AST::Variable)
+        return base if base.is_a?(Value)
+        return lookup(base.to_s) if base.is_a?(String) || base.is_a?(Symbol)
+
+        value = base.is_a?(AST::Literal) ? base.value : base
+        Value.from_ruby(value)
+      rescue ArgumentError
+        UndefinedValue.new
+      end
+
+      # :reek:FeatureEnvy
+      def resolve_path_segment(current, segment)
+        key = extract_reference_key(segment)
+        return UndefinedValue.new if key.is_a?(UndefinedValue)
+
+        return current.fetch(key) if current.is_a?(ObjectValue)
+        return current.fetch_index(key) if current.is_a?(ArrayValue)
+
+        UndefinedValue.new
+      end
+
+      # :reek:FeatureEnvy
+      def resolve_reference_path(current, path)
+        path.each do |segment|
+          current = resolve_path_segment(current, segment)
+          return current if current.is_a?(UndefinedValue)
+        end
+        current
+      end
+
+      # :reek:TooManyStatements
+      # :reek:FeatureEnvy
+      def extract_reference_key(segment)
+        value = segment.is_a?(AST::RefArg) ? segment.value : segment
+        return value.value if value.is_a?(AST::Literal)
+        return resolve_reference_variable(value) if value.is_a?(AST::Variable)
+        return value.to_ruby if value.is_a?(Value)
+
+        Value.from_ruby(value).to_ruby
+      rescue ArgumentError
+        UndefinedValue.new
+      end
+
+      # :reek:FeatureEnvy
+      def resolve_reference_variable(value)
+        resolved = lookup(value.name)
+        return resolved if resolved.is_a?(UndefinedValue)
+
+        resolved.to_ruby
+      end
+    end
+  end
+end

data/lib/ruby/rego/environment.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+require_relative "ast"
+require_relative "errors"
+require_relative "value"
+require_relative "builtins/registry"
+require_relative "memoization"
+require_relative "environment/overrides"
+require_relative "environment/reference_resolution"
+
+module Ruby
+  module Rego
+    # Execution environment for evaluating Rego policies.
+    # :reek:TooManyInstanceVariables
+    # rubocop:disable Metrics/ClassLength
+    class Environment
+      # Encapsulates environment state for pooling.
+      State = Struct.new(:input, :data, :rules, :builtin_registry, keyword_init: true)
+
+      RESERVED_BINDINGS = {
+        "input" => :input,
+        "data" => :data
+      }.freeze
+      RESERVED_NAMES = RESERVED_BINDINGS.keys.freeze
+
+      # Input document as a Rego value.
+      #
+      # @return [Value]
+      attr_reader :input
+
+      # Data document as a Rego value.
+      #
+      # @return [Value]
+      attr_reader :data
+
+      # Rule index by name.
+      #
+      # @return [Hash]
+      attr_reader :rules
+
+      # Builtin registry in use.
+      #
+      # @return [Builtins::BuiltinRegistry, Builtins::BuiltinRegistryOverlay]
+      attr_reader :builtin_registry
+
+      # Memoization store for evaluation caches.
+      #
+      # @return [Memoization::Store]
+      attr_reader :memoization
+
+      # Create an evaluation environment.
+      #
+      # @param input [Object] input document
+      # @param data [Object] data document
+      # @param rules [Hash] rule index
+      # @param builtin_registry [Builtins::BuiltinRegistry, Builtins::BuiltinRegistryOverlay] registry
+      def initialize(input: {}, data: {}, rules: {}, builtin_registry: Builtins::BuiltinRegistry.instance)
+        @memoization = Memoization::Store.new
+        @builtin_registry = builtin_registry
+        @locals = [fresh_scope] # @type var locals: Array[Hash[String, Value]]
+        @scope_pool = [] # @type var @scope_pool: Array[Hash[String, Value]]
+        apply_state(State.new(input: input, data: data, rules: rules, builtin_registry: builtin_registry))
+      end
+
+      # Build an environment from a state struct.
+      #
+      # @param state [State]
+      # @return [Environment]
+      def self.from_state(state)
+        new(
+          input: state.input,
+          data: state.data,
+          rules: state.rules,
+          builtin_registry: state.builtin_registry
+        )
+      end
+
+      include EnvironmentOverrides
+      include EnvironmentReferenceResolution
+
+      # Push a new scope for local bindings.
+      #
+      # @return [Environment] self
+      def push_scope
+        scope = scope_pool.pop
+        scope ||= fresh_scope
+        scope.clear
+        locals << scope
+        self
+      end
+
+      # Pop the latest local scope.
+      #
+      # @return [void]
+      def pop_scope
+        return nil if locals.length <= 1
+
+        scope = locals.pop # @type var scope: Hash[String, Value]
+        scope.clear
+        scope_pool << scope
+        nil
+      end
+
+      # Reset environment state for reuse.
+      #
+      # @param state [State] reset state
+      # @return [Environment] self
+      def reset!(state)
+        apply_state(state)
+        reset_scopes
+        memoization.reset!
+        self
+      end
+
+      # Reset environment state for reuse without mutation semantics.
+      #
+      # @param state [State] reset state
+      # @return [Environment]
+      def reset(state)
+        reset!(state)
+      end
+
+      # Reset the environment for pool reuse.
+      #
+      # @return [Environment]
+      def prepare_for_pool
+        empty_hash = {} # @type var empty_hash: Hash[untyped, untyped]
+        reset(State.new(input: empty_hash, data: empty_hash, rules: rules, builtin_registry: builtin_registry))
+      end
+
+      # Bind a local name to a value.
+      #
+      # @param name [String, Symbol] binding name
+      # @param value [Object] value to bind
+      # @return [Value] bound value
+      def bind(name, value)
+        name = name.to_s
+        raise Error, "Cannot bind reserved name: #{name}" if RESERVED_NAMES.include?(name)
+
+        value = Value.from_ruby(value)
+        locals.last[name] = value
+        value
+      end
+
+      # Lookup a binding from the current scope chain.
+      #
+      # @param name [String, Symbol] binding name
+      # @return [Value] resolved value or undefined
+      # :reek:TooManyStatements
+      def lookup(name)
+        name = name.to_s
+        reserved = RESERVED_BINDINGS[name]
+        return public_send(reserved) if reserved
+
+        locals.reverse_each do |scope|
+          return scope[name] if scope.key?(name)
+        end
+
+        UndefinedValue.new
+      end
+
+      # Check whether a name is bound in any local scope.
+      #
+      # @param name [String, Symbol] binding name
+      # @return [Boolean]
+      def local_bound?(name)
+        name = name.to_s
+        return false if RESERVED_NAMES.include?(name)
+
+        locals.reverse_each do |scope|
+          return true if scope.key?(name)
+        end
+
+        false
+      end
+
+      # Execute a block with additional temporary bindings.
+      #
+      # @param bindings [Hash{String, Symbol => Object}] bindings to apply
+      # @yieldreturn [Object]
+      # @return [Object] block result
+      def with_bindings(bindings)
+        push_scope
+        bindings.each { |name, value| bind(name, value) }
+        yield
+      ensure
+        pop_scope
+      end
+
+      # Execute a block with an overridden builtin registry.
+      #
+      # @param registry [Builtins::BuiltinRegistry, Builtins::BuiltinRegistryOverlay] registry to use
+      # @yieldparam environment [Environment]
+      # @return [Object] block result
+      def with_builtin_registry(registry)
+        original = @builtin_registry
+        memoization.with_context do
+          @builtin_registry = registry
+          yield self
+        end
+      ensure
+        @builtin_registry = original
+      end
+
+      private
+
+      attr_reader :locals, :scope_pool
+
+      def fresh_scope
+        {} # @type var scope: Hash[String, Value]
+      end
+
+      def reset_scopes
+        locals.each(&:clear)
+        scope_pool.clear
+        base_scope = locals.first || fresh_scope
+        locals.replace([base_scope])
+        base_scope.clear
+      end
+
+      def apply_state(state)
+        @input = Value.from_ruby(state.input)
+        @data = Value.from_ruby(state.data)
+        @rules = state.rules.dup
+        @builtin_registry = state.builtin_registry
+      end
+    end
+    # rubocop:enable Metrics/ClassLength
+  end
+end

data/lib/ruby/rego/environment_pool.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative "environment"
+
+module Ruby
+  module Rego
+    # Pools Environment instances for reuse across evaluations.
+    # Thread-safe for concurrent checkouts/checkins.
+    class EnvironmentPool
+      # @param max_size [Integer, nil] maximum pool size for reuse (nil means unbounded)
+      # :reek:ControlParameter
+      def initialize(max_size: nil)
+        pool = [] # @type var pool: Array[Environment]
+        @pool = pool
+        @max_size = normalized_max_size(max_size)
+        @mutex = Mutex.new
+      end
+
+      # @param state [Environment::State]
+      # @return [Environment]
+      def checkout(state)
+        @mutex.synchronize do
+          environment = @pool.pop # @type var environment: Environment?
+          return Environment.from_state(state) unless environment
+
+          environment.reset!(state)
+        end
+      end
+
+      # @param environment [Environment]
+      # @return [void]
+      def checkin(environment)
+        @mutex.synchronize do
+          return nil if max_size_full?(@pool.length)
+
+          environment.prepare_for_pool
+          @pool << environment
+        end
+        nil
+      end
+
+      private
+
+      attr_reader :max_size
+
+      def max_size_full?(current_size)
+        return false if max_size.equal?(unbounded)
+
+        current_size >= max_size
+      end
+
+      def unbounded
+        @unbounded ||= Object.new.freeze
+      end
+
+      # :reek:NilCheck
+      def normalized_max_size(value)
+        case value
+        when nil
+          unbounded
+        when Integer
+          raise ArgumentError, "max_size must be non-negative" if value.negative?
+
+          value
+        else
+          raise ArgumentError, "max_size must be an Integer"
+        end
+      end
+    end
+  end
+end

data/lib/ruby/rego/error_handling.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+require_relative "location"
+
+module Ruby
+  # Ruby Rego implementation namespace.
+  module Rego
+    # Internal helper for wrapping unexpected errors in public API calls.
+    module ErrorHandling
+      # Wrap a public API call with standardized error handling.
+      #
+      # @param context [String] error context label
+      # @yieldreturn [Object]
+      # @return [Object]
+      # :reek:TooManyStatements
+      # :reek:UncommunicativeVariableName
+      def self.wrap(context)
+        yield
+      rescue Error => e
+        raise e
+      rescue StandardError => e
+        raise build_error(context, e), cause: e
+      end
+
+      # Extract a location from an error-like object.
+      #
+      # @param error [Object] error to inspect
+      # @return [Location, nil]
+      # :reek:ManualDispatch
+      # :reek:TooManyStatements
+      def self.location_from(error)
+        location = error.respond_to?(:location) ? error.location : nil
+        return location if location
+
+        line = error.respond_to?(:line) ? error.line : nil
+        column = error.respond_to?(:column) ? error.column : nil
+
+        return Location.new(line: line, column: column) if line.is_a?(Integer) && column.is_a?(Integer)
+
+        nil
+      end
+
+      # Build a wrapped error from an exception.
+      #
+      # @param context [String]
+      # @param error [StandardError]
+      # @return [Error]
+      def self.build_error(context, error)
+        Error.new("Rego #{context} failed: #{error.message}", location: location_from(error))
+      end
+
+      private_class_method :build_error
+    end
+
+    private_constant :ErrorHandling
+  end
+end

data/lib/ruby/rego/error_payload.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+
+module Ruby
+  module Rego
+    # Normalizes error objects for structured result payloads.
+    module ErrorPayload
+      # @param error [Object]
+      # @return [Object]
+      def self.from(error)
+        return error if error.is_a?(Hash) || error.is_a?(String)
+        return error.to_h if error.is_a?(Error)
+        return standard_error_payload(error) if error.is_a?(StandardError)
+
+        error.to_s
+      end
+
+      # @param error [StandardError]
+      # @return [Hash{Symbol => Object}]
+      # :reek:ManualDispatch
+      def self.standard_error_payload(error)
+        payload = { message: error.message }
+        return payload unless error.respond_to?(:location)
+
+        location = error.location
+        payload[:location] = location.to_s if location
+        payload
+      end
+
+      private_class_method :standard_error_payload
+    end
+  end
+end

data/lib/ruby/rego/errors.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+require_relative "location"
+
+module Ruby
+  # Ruby Rego implementation namespace.
+  module Rego
+    # Shared formatting helpers for error message details.
+    module ErrorFormatting
+      # Format detail key/value pairs for error messages.
+      #
+      # @param details [Hash{Symbol => Object}]
+      # @return [String]
+      def self.format_details(details)
+        details.compact.map { |key, value| "#{key}: #{value}" }.join(", ")
+      end
+    end
+
+    private_constant :ErrorFormatting
+
+    # Base error for all Ruby::Rego exceptions.
+    class Error < StandardError
+      # @return [Location, nil]
+      attr_reader :location
+
+      # Create a new error with optional location details.
+      #
+      # @param message [String, nil] error message
+      # @param location [Location, nil] source location
+      def initialize(message = nil, location: nil)
+        @raw_message = message
+        @location = location
+        super(compose_message(message))
+      end
+
+      # Serialize the error to a hash.
+      #
+      # @return [Hash{Symbol => Object}]
+      def to_h
+        {
+          message: raw_message,
+          type: self.class.name,
+          location: location&.to_s
+        }
+      end
+
+      private
+
+      attr_reader :raw_message
+
+      def compose_message(message)
+        [message, location&.then { |loc| "(#{loc})" }].compact.join(" ")
+      end
+    end
+
+    # Error raised during tokenization.
+    class LexerError < Error
+      # @return [Integer]
+      attr_reader :line
+
+      # @return [Integer]
+      attr_reader :column
+
+      # Create a lexer error.
+      #
+      # @param message [String] error message
+      # @param line [Integer] line number
+      # @param column [Integer] column number
+      # @param offset [Integer, nil] character offset
+      # @param length [Integer, nil] token length
+      def initialize(message, line:, column:, offset: nil, length: nil)
+        @line = line
+        @column = column
+        location = Location.new(line: line, column: column, offset: offset, length: length)
+        super(message, location: location)
+      end
+    end
+
+    # Error raised during parsing.
+    class ParserError < Error
+      # @return [Integer]
+      attr_reader :line
+
+      # @return [Integer]
+      attr_reader :column
+
+      # @return [String, nil]
+      attr_reader :context
+
+      # Create a parser error.
+      #
+      # @param message [String] error message
+      # @param context [String, nil] token context
+      # @param location [Location] error location
+      def initialize(message, location:, context: nil)
+        @line = location.line
+        @column = location.column
+        @context = context
+        composed = context ? "#{message} (context: #{context})" : message
+        super(composed, location: location)
+      end
+
+      # Build an error from a position hash or location.
+      #
+      # @param message [String] error message
+      # @param position [Hash, Location] source position
+      # @param context [String, nil] token context
+      # @return [ParserError]
+      def self.from_position(message, position:, context: nil)
+        location = Location.from(position)
+        new(message, location: location, context: context)
+      end
+    end
+
+    # Error raised during module compilation.
+    class CompilationError < Error
+    end
+
+    # Error raised during evaluation.
+    class EvaluationError < Error
+      # @return [Object, nil]
+      attr_reader :rule
+
+      # Create an evaluation error.
+      #
+      # @param message [String] error message
+      # @param rule [Object, nil] rule context
+      # @param location [Location, nil] source location
+      def initialize(message, rule: nil, location: nil)
+        @rule = rule
+        details = ErrorFormatting.format_details(rule: rule)
+        composed = details.empty? ? message : "#{message} (#{details})"
+        super(composed, location: location)
+      end
+    end
+
+    # Error raised for type-checking issues.
+    class TypeError < Error
+      # @return [Object, nil]
+      attr_reader :expected
+
+      # @return [Object, nil]
+      attr_reader :actual
+
+      # @return [String, nil]
+      attr_reader :context
+
+      # Create a type error.
+      #
+      # @param message [String] error message
+      # @param expected [Object, nil] expected type or value
+      # @param actual [Object, nil] actual type or value
+      # @param context [String, nil] error context
+      # @param location [Location, nil] source location
+      def initialize(message, expected: nil, actual: nil, context: nil, location: nil)
+        @expected = expected
+        @actual = actual
+        @context = context
+        details = ErrorFormatting.format_details(expected: expected, actual: actual, context: context)
+        composed = details.empty? ? message : "#{message} (#{details})"
+        super(composed, location: location)
+      end
+    end
+
+    # Error raised for invalid builtin arguments.
+    class BuiltinArgumentError < TypeError
+    end
+
+    # Error raised when object keys normalize to the same value.
+    class ObjectKeyConflictError < Error
+    end
+
+    # Error raised during unification/pattern matching.
+    class UnificationError < Error
+      # @return [Object, nil]
+      attr_reader :pattern
+
+      # @return [Object, nil]
+      attr_reader :value
+
+      # Create a unification error.
+      #
+      # @param message [String] error message
+      # @param pattern [Object, nil] pattern being matched
+      # @param value [Object, nil] value being matched
+      # @param location [Location, nil] source location
+      def initialize(message, pattern: nil, value: nil, location: nil)
+        @pattern = pattern
+        @value = value
+        details = ErrorFormatting.format_details(pattern: pattern, value: value)
+        composed = details.empty? ? message : "#{message} (#{details})"
+        super(composed, location: location)
+      end
+    end
+  end
+end