ruby-rego 0.1.0

data/lib/ruby/rego/parser/rules.rb

@@ -0,0 +1,310 @@
+# frozen_string_literal: true
+
+module Ruby
+  module Rego
+    # Parsing helpers for rules and module declarations.
+    # :reek:TooManyMethods
+    # :reek:DataClump
+    # :reek:RepeatedConditional
+    # rubocop:disable Metrics/ClassLength
+    class Parser
+      private
+
+      # :reek:TooManyStatements
+      def parse_module
+        consume_newlines
+        package = parse_package
+        imports = [] # @type var imports: Array[AST::Import]
+        rules = [] # @type var rules: Array[AST::Rule]
+
+        consume_newlines
+        until at_end?
+          parse_statement(imports, rules)
+          consume_newlines
+        end
+
+        AST::Module.new(package: package, imports: imports, rules: rules, location: package.location)
+      end
+
+      # :reek:UncommunicativeVariableName
+      # :reek:TooManyStatements
+      def parse_statement(imports, rules)
+        consume_newlines
+        return if at_end?
+
+        if match?(TokenType::IMPORT)
+          imports << parse_import
+        else
+          rules << parse_rule
+        end
+      rescue ParserError => e
+        record_error(e)
+        synchronize
+      end
+
+      def parse_package
+        keyword = consume(TokenType::PACKAGE, "Expected package declaration.")
+        path = parse_path(IdentifierContext.new(name: "package", allowed_types: PACKAGE_PATH_TOKEN_TYPES))
+        AST::Package.new(path: path, location: keyword.location)
+      end
+
+      def parse_import
+        keyword = consume(TokenType::IMPORT, "Expected import declaration.")
+        path = parse_path(IdentifierContext.new(name: "import", allowed_types: IMPORT_PATH_TOKEN_TYPES))
+        alias_name = parse_import_alias
+
+        AST::Import.new(path: path, alias_name: alias_name, location: keyword.location)
+      end
+
+      def parse_import_alias
+        return nil unless match?(TokenType::AS)
+
+        advance
+        parse_identifier(IdentifierContext.new(name: "import alias", allowed_types: PACKAGE_PATH_TOKEN_TYPES))
+      end
+
+      # :reek:TooManyStatements
+      def parse_rule
+        default_token = consume_default_keyword
+        name_token = current_token
+        name_path = parse_rule_name_path
+        name = name_path.first
+        head = parse_rule_head(name, name_token)
+        head = apply_rule_head_path(head, name_path.drop(1), name_token)
+        head = mark_default_head(head) if default_token
+        definition = parse_rule_definition(default_token, head)
+        validate_rule_definition(default_token, head, definition)
+
+        build_rule_node(name: name, head: head, name_token: name_token, definition: definition)
+      end
+
+      def consume_default_keyword
+        match?(TokenType::DEFAULT) ? advance : nil
+      end
+
+      # :reek:DuplicateMethodCall
+      # rubocop:disable Metrics/MethodLength
+      def parse_rule_name_path
+        segments = [] # @type var segments: Array[String]
+        context = IdentifierContext.new(name: "rule", allowed_types: PACKAGE_PATH_TOKEN_TYPES)
+        segments << parse_identifier(context)
+
+        loop do
+          if match?(TokenType::DOT)
+            advance
+            segments << parse_identifier(context)
+            next
+          end
+
+          break unless bracket_string_segment?
+
+          segment = parse_bracket_path_segment
+          break unless segment
+
+          segments << segment
+        end
+
+        segments
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      # :reek:UtilityFunction
+      def mark_default_head(head)
+        head.merge(default: true)
+      end
+
+      # :reek:NilCheck
+      # :reek:ControlParameter
+      def parse_default_value(default_token, head)
+        return nil unless default_token
+
+        default_value = head[:value]
+        parse_error("Expected default rule value.") if default_value.nil?
+        default_value
+      end
+
+      # :reek:ControlParameter
+      def parse_non_default_body(default_token)
+        return nil if default_token
+        return nil unless match?(TokenType::IF, TokenType::LBRACE)
+
+        parse_rule_body
+      end
+
+      def parse_rule_definition(default_token, head)
+        default_value = parse_default_value(default_token, head)
+        body = parse_non_default_body(default_token)
+        else_clause = parse_else_clause_for_definition(default_token)
+
+        {
+          default_value: default_value,
+          body: body,
+          else_clause: else_clause
+        }
+      end
+
+      # :reek:ControlParameter
+      def parse_else_clause_for_definition(default_token)
+        consume_newlines
+        parse_error("Default rules cannot have else clauses.") if default_token && match?(TokenType::ELSE)
+        parse_else_clause_if_present
+      end
+
+      # :reek:FeatureEnvy
+      # :reek:ControlParameter
+      def validate_rule_definition(default_token, head, definition)
+        return if default_token
+        return unless head[:type] == :complete
+        return if head[:value] || definition[:body]
+
+        parse_error("Expected rule body or value.")
+      end
+
+      def parse_else_clause_if_present
+        return nil unless match?(TokenType::ELSE)
+
+        parse_else_clause
+      end
+
+      # :reek:UtilityFunction
+      # :reek:LongParameterList
+      def build_rule_node(name:, head:, name_token:, definition:)
+        AST::Rule.new(
+          name: name,
+          head: head,
+          body: definition[:body],
+          default_value: definition[:default_value],
+          else_clause: definition[:else_clause],
+          location: name_token.location
+        )
+      end
+
+      def parse_rule_head(name, name_token)
+        return parse_contains_rule_head(name, name_token) if match?(TokenType::CONTAINS)
+        return parse_function_rule_head(name, name_token) if match?(TokenType::LPAREN)
+        return parse_bracket_rule_head(name, name_token) if match?(TokenType::LBRACKET)
+
+        build_rule_head(:complete, name, name_token, value: parse_rule_value)
+      end
+
+      def parse_contains_rule_head(name, name_token)
+        advance
+        term = parse_expression
+        build_rule_head(:partial_set, name, name_token, term: term)
+      end
+
+      def parse_function_rule_head(name, name_token)
+        args = parse_rule_head_args
+        value = parse_rule_value
+        build_rule_head(:function, name, name_token, args: args, value: value)
+      end
+
+      def parse_bracket_rule_head(name, name_token)
+        key = parse_rule_head_key
+        return parse_partial_object_rule_head(name, name_token, key) if match?(TokenType::ASSIGN, TokenType::UNIFY)
+
+        build_rule_head(:partial_set, name, name_token, term: key)
+      end
+
+      def parse_partial_object_rule_head(name, name_token, key)
+        advance
+        value = parse_expression
+        build_rule_head(:partial_object, name, name_token, key: key, value: value)
+      end
+
+      # :reek:UtilityFunction
+      # :reek:LongParameterList
+      def build_rule_head(type, name, name_token, **attrs)
+        { type: type, name: name, location: name_token.location }.merge(attrs)
+      end
+
+      def apply_rule_head_path(head, segments, name_token)
+        return head if segments.empty?
+        return nested_rule_head(head, segments, name_token) if head[:type] == :complete
+
+        parse_error("Rule head references require complete rule definitions.")
+      end
+
+      # :reek:UtilityFunction
+      # rubocop:disable Metrics/MethodLength
+      def nested_rule_head(head, segments, name_token)
+        location = name_token.location
+        key_segment = segments.first
+        remaining = segments.drop(1)
+        value_node = head[:value] || AST::BooleanLiteral.new(value: true, location: location)
+
+        remaining.reverse_each do |segment|
+          key_node = AST::StringLiteral.new(value: segment, location: location)
+          value_node = AST::ObjectLiteral.new(pairs: [[key_node, value_node]], location: location)
+        end
+
+        head.merge(
+          type: :partial_object,
+          key: AST::StringLiteral.new(value: key_segment, location: location),
+          value: value_node,
+          nested: remaining.any?
+        )
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      # :reek:TooManyStatements
+      def parse_rule_head_args
+        parse_parenthesized_expression_list(
+          open_message: "Expected '(' after rule name.",
+          close_message: "Expected ')' after rule arguments."
+        )
+      end
+
+      # :reek:TooManyStatements
+      def parse_rule_head_key
+        consume(TokenType::LBRACKET, "Expected '[' after rule name.")
+        consume_newlines
+        key = parse_expression
+        consume_newlines
+        consume(TokenType::RBRACKET, "Expected ']' after rule key.")
+        key
+      end
+
+      def parse_rule_value
+        return nil unless match?(TokenType::ASSIGN, TokenType::UNIFY)
+
+        advance
+        parse_expression
+      end
+
+      def parse_rule_body
+        advance if match?(TokenType::IF)
+        return parse_braced_rule_body if match?(TokenType::LBRACE)
+
+        parse_query(TokenType::ELSE, TokenType::EOF, TokenType::NEWLINE, newline_delimiter: false)
+      end
+
+      # :reek:TooManyStatements
+      def parse_braced_rule_body
+        advance
+        consume_newlines
+        return parse_empty_rule_body if rbrace_token?
+
+        body = parse_query(TokenType::RBRACE, newline_delimiter: true)
+        consume(TokenType::RBRACE, "Expected '}' after rule body.")
+        body
+      end
+
+      def parse_empty_rule_body
+        advance
+        []
+      end
+
+      def parse_else_clause
+        keyword = consume(TokenType::ELSE, "Expected 'else' clause.")
+        value = nil
+        value = parse_rule_value if match?(TokenType::ASSIGN, TokenType::UNIFY)
+        body = parse_rule_body if match?(TokenType::IF, TokenType::LBRACE)
+        else_clause = parse_else_clause_if_present
+
+        { value: value, body: body, location: keyword.location, else_clause: else_clause }
+      end
+    end
+    # rubocop:enable Metrics/ClassLength
+  end
+end

data/lib/ruby/rego/parser.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+require_relative "token"
+require_relative "ast"
+require_relative "parser/precedence"
+require_relative "parser/collections"
+require_relative "parser/expressions"
+require_relative "parser/query"
+require_relative "parser/references"
+require_relative "parser/rules"
+
+module Ruby
+  module Rego
+    # Parses a token stream into an AST module.
+    # rubocop:disable Metrics/ClassLength
+    # :reek:TooManyMethods
+    # :reek:TooManyConstants
+    # :reek:RepeatedConditional
+    # :reek:DataClump
+    class Parser
+      IDENTIFIER_TOKEN_TYPES = [TokenType::IDENT, TokenType::DATA, TokenType::INPUT].freeze
+      IDENTIFIER_TOKEN_NAMES = {
+        TokenType::DATA => "data",
+        TokenType::INPUT => "input"
+      }.freeze
+      BINARY_OPERATOR_MAP = {
+        TokenType::ASSIGN => :assign,
+        TokenType::UNIFY => :unify,
+        TokenType::IN => :in,
+        TokenType::OR => :or,
+        TokenType::AND => :and,
+        TokenType::EQ => :eq,
+        TokenType::NEQ => :neq,
+        TokenType::LT => :lt,
+        TokenType::LTE => :lte,
+        TokenType::GT => :gt,
+        TokenType::GTE => :gte,
+        TokenType::PLUS => :plus,
+        TokenType::MINUS => :minus,
+        TokenType::STAR => :mult,
+        TokenType::SLASH => :div,
+        TokenType::PERCENT => :mod
+      }.freeze
+      UNARY_OPERATOR_MAP = {
+        TokenType::NOT => :not,
+        TokenType::MINUS => :minus
+      }.freeze
+      PRIMARY_PARSERS = {
+        TokenType::STRING => :parse_string_literal,
+        TokenType::TEMPLATE_STRING => :parse_template_string,
+        TokenType::RAW_STRING => :parse_string_literal,
+        TokenType::RAW_TEMPLATE_STRING => :parse_template_string,
+        TokenType::NUMBER => :parse_number_literal,
+        TokenType::TRUE => :parse_boolean_literal,
+        TokenType::FALSE => :parse_boolean_literal,
+        TokenType::NULL => :parse_null_literal,
+        TokenType::NOT => :parse_unary_expression,
+        TokenType::MINUS => :parse_unary_expression,
+        TokenType::EVERY => :parse_every,
+        TokenType::LPAREN => :parse_parenthesized_expression,
+        TokenType::LBRACKET => :parse_array,
+        TokenType::LBRACE => :parse_braced_literal,
+        TokenType::IDENT => :parse_identifier_expression,
+        TokenType::DATA => :parse_identifier_expression,
+        TokenType::INPUT => :parse_identifier_expression,
+        TokenType::UNDERSCORE => :parse_identifier_expression
+      }.freeze
+      PACKAGE_PATH_TOKEN_TYPES = [TokenType::IDENT].freeze
+      IMPORT_PATH_TOKEN_TYPES = IDENTIFIER_TOKEN_TYPES
+      # Bundles identifier parsing configuration for error messages and validation.
+      IdentifierContext = Struct.new(:name, :allowed_types, keyword_init: true)
+
+      # Create a parser from a token list.
+      #
+      # @param tokens [Array<Token>] token stream
+      def initialize(tokens)
+        @tokens = tokens.dup
+        @current = 0
+        @errors = [] # @type var errors: Array[ParserError]
+      end
+
+      # Parse the token stream into an AST module.
+      #
+      # @return [AST::Module] parsed module
+      def parse
+        module_node = parse_module
+        raise errors.first if errors.any?
+
+        module_node
+      end
+
+      private
+
+      attr_reader :errors, :tokens
+
+      def current_token
+        safe_token_at(@current)
+      end
+
+      def peek(distance = 1)
+        safe_token_at(@current + distance)
+      end
+
+      def advance
+        previous = current_token
+        @current += 1 unless at_end?
+        previous
+      end
+
+      # :reek:ControlParameter
+      def consume(type, message = nil)
+        return advance if match?(type)
+
+        parse_error(message || "Expected #{type} but found #{current_token.type}.")
+      end
+
+      def match?(*types)
+        types.include?(current_token.type)
+      end
+
+      def pipe_token?
+        match?(TokenType::PIPE)
+      end
+
+      def rbrace_token?
+        match?(TokenType::RBRACE)
+      end
+
+      def newline_token?
+        match?(TokenType::NEWLINE)
+      end
+
+      def consume_newlines
+        advance while newline_token?
+      end
+
+      def at_end?
+        current_token.type == TokenType::EOF
+      end
+
+      def parse_error(message)
+        token = current_token
+        position = token&.location || { line: 1, column: 1 }
+        raise ParserError.from_position(message, position: position, context: token&.to_s)
+      end
+
+      def synchronize
+        advance
+
+        until at_end?
+          return if match?(TokenType::SEMICOLON, TokenType::NEWLINE)
+          return if match?(TokenType::PACKAGE, TokenType::IMPORT, TokenType::DEFAULT, TokenType::IDENT)
+
+          advance
+        end
+      end
+
+      def record_error(error)
+        errors << error
+      end
+
+      # Shared parsing helpers that do not depend on parser state.
+      module Helpers
+        def self.precedence_of(operator)
+          Precedence::BINARY.fetch(operator, Precedence::LOWEST)
+        end
+
+        def self.normalize_reference_base(base)
+          path = [] # @type var path: Array[AST::RefArg]
+          return [base, path] unless base.is_a?(AST::Reference)
+
+          reference = base # @type var reference: AST::Reference
+          [reference.base, reference.path.dup]
+        end
+
+        def self.variable_name_for(token)
+          token_type = token.type
+          case token_type
+          when TokenType::IDENT
+            token.value.to_s
+          when TokenType::UNDERSCORE
+            "_"
+          else
+            IDENTIFIER_TOKEN_NAMES.fetch(token_type) { token_type.to_s.downcase }
+          end
+        end
+      end
+
+      def safe_token_at(index)
+        tokens[index] || tokens[-1]
+      end
+
+      class << self
+        # Parse a single Rego expression from source.
+        #
+        # @param source [String]
+        # @return [Object]
+        def parse_expression_from_string(source)
+          tokens = Lexer.new(source.to_s).tokenize
+          parser = new(tokens)
+          expression = parser.send(:parse_expression)
+          parser.send(:consume, TokenType::EOF, "Expected end of expression.")
+          expression
+        end
+      end
+    end
+    # rubocop:enable Metrics/ClassLength
+  end
+end

data/lib/ruby/rego/policy.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "compiler"
+require_relative "evaluator"
+require_relative "environment_pool"
+require_relative "error_handling"
+
+module Ruby
+  module Rego
+    # Compiled policy for reuse across evaluations.
+    class Policy
+      # Create a compiled policy from source.
+      #
+      # @param source [String] Rego source
+      # @param environment_pool [EnvironmentPool] optional pool override
+      def initialize(source, environment_pool: EnvironmentPool.new)
+        @source = source.to_s
+        @compiled_module = Ruby::Rego.compile(@source)
+        @environment_pool = environment_pool
+      end
+
+      # Evaluate the policy with the provided input and query.
+      #
+      # @param input [Object] input document
+      # @param data [Object] data document
+      # @param query [Object, nil] query path
+      # @return [Result] evaluation result
+      def evaluate(input: {}, data: {}, query: nil)
+        ErrorHandling.wrap("evaluation") { evaluate_with_pool(input: input, data: data, query: query) }
+      end
+
+      private
+
+      attr_reader :compiled_module, :environment_pool, :source
+
+      def evaluate_with_pool(input:, data:, query:)
+        state = Environment::State.new(
+          input: input,
+          data: data,
+          rules: compiled_module.rules_by_name,
+          builtin_registry: Builtins::BuiltinRegistry.instance
+        )
+        environment = environment_pool.checkout(state)
+        Evaluator.from_environment(compiled_module, environment).evaluate(query)
+      ensure
+        environment_pool.checkin(environment) if environment
+      end
+    end
+  end
+end

data/lib/ruby/rego/result.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "error_payload"
+require_relative "value"
+
+module Ruby
+  module Rego
+    # Represents the outcome of evaluating a policy or expression.
+    class Result
+      # Evaluated value.
+      #
+      # @return [Value]
+      attr_reader :value
+
+      # Variable bindings captured during evaluation.
+      #
+      # @return [Hash{String => Value}]
+      attr_reader :bindings
+
+      # True when evaluation succeeded and produced a value.
+      #
+      # @return [Boolean]
+      attr_reader :success
+
+      # Errors collected during evaluation.
+      #
+      # @return [Array<Object>]
+      attr_reader :errors
+
+      # Create a result wrapper.
+      #
+      # @param value [Object] evaluation value
+      # @param success [Boolean] success flag
+      # @param bindings [Hash{String, Symbol => Object}] variable bindings
+      # @param errors [Array<Object>] collected errors
+      def initialize(value:, success:, bindings: {}, errors: [])
+        @value = Value.from_ruby(value)
+        @bindings = {} # @type var @bindings: Hash[String, Value]
+        add_bindings(bindings)
+        @success = success
+        @errors = errors.dup
+      end
+
+      # Convenience success predicate.
+      #
+      # @return [Boolean]
+      def success?
+        success
+      end
+
+      # True when the value is undefined.
+      #
+      # @return [Boolean]
+      def undefined?
+        value.is_a?(UndefinedValue)
+      end
+
+      # Convert the result to a serializable hash.
+      #
+      # @return [Hash{Symbol => Object}]
+      def to_h
+        {
+          value: value.to_ruby,
+          bindings: bindings.transform_values(&:to_ruby),
+          success: success,
+          errors: errors.map { |error| ErrorPayload.from(error) }
+        }
+      end
+
+      # Serialize the result as JSON.
+      #
+      # @param _args [Array<Object>]
+      # @return [String]
+      def to_json(*args)
+        options = args.first
+        return JSON.generate(to_h) unless options.is_a?(Hash)
+
+        JSON.generate(to_h, options)
+      end
+
+      private
+
+      def add_bindings(bindings)
+        bindings.each do |(name, binding_value)|
+          @bindings[name.to_s] = Value.from_ruby(binding_value)
+        end
+      end
+    end
+  end
+end