ruby-rego 0.1.0

data/lib/ruby/rego/evaluator/variable_collector.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+module Ruby
+  module Rego
+    class Evaluator
+      # Shared traversal helpers for variable collection.
+      module VariableCollectorHelpers
+        NODE_COLLECTORS = {
+          AST::Variable => ->(node, collector) { collector.send(:add_name, node.name) },
+          AST::SomeDecl => ->(node, collector) { collector.send(:collect_some_decl, node) },
+          AST::Every => ->(node, collector) { collector.send(:collect_every, node) },
+          AST::QueryLiteral => ->(node, collector) { collector.send(:collect_node, node.expression) },
+          AST::ArrayComprehension => lambda do |node, collector|
+            collector.send(:collect_comprehension, [node.term], node.body)
+          end,
+          AST::SetComprehension => lambda do |node, collector|
+            collector.send(:collect_comprehension, [node.term], node.body)
+          end,
+          AST::ObjectComprehension => lambda do |node, collector|
+            key_node, value_node = node.term
+            collector.send(:collect_comprehension, [key_node, value_node], node.body)
+          end
+        }.freeze
+
+        CHILDREN_EXTRACTORS = {
+          AST::Reference => ->(node) { [node.base] + node.path.map(&:value) },
+          AST::BinaryOp => ->(node) { [node.left, node.right] },
+          AST::UnaryOp => ->(node) { [node.operand] },
+          AST::ArrayLiteral => :elements.to_proc,
+          AST::SetLiteral => :elements.to_proc,
+          AST::ObjectLiteral => lambda do |node|
+            node.pairs.flat_map { |key_node, value_node| [key_node, value_node] }
+          end,
+          AST::ArrayComprehension => ->(node) { [node.term] },
+          AST::SetComprehension => ->(node) { [node.term] },
+          AST::ObjectComprehension => lambda do |node|
+            key_node, value_node = node.term
+            [key_node, value_node]
+          end,
+          AST::Call => ->(node) { node.args.dup }
+        }.freeze
+
+        def self.collector_for(node)
+          NODE_COLLECTORS[node.class]
+        end
+
+        def self.children_for(node)
+          extractor = CHILDREN_EXTRACTORS[node.class]
+          return [] unless extractor
+
+          extractor.call(node)
+        end
+
+        def self.comprehension_node?(node)
+          node.is_a?(AST::ArrayComprehension) || node.is_a?(AST::SetComprehension) || node.is_a?(AST::ObjectComprehension)
+        end
+      end
+
+      # Collects variable names that become bound inside query bodies.
+      class BoundVariableCollector
+        def initialize
+          @explicit_names = [] # @type var @explicit_names: Array[String]
+          @unify_names = [] # @type var @unify_names: Array[String]
+        end
+
+        # @param literals [Array<Object>]
+        # @return [Array<String>]
+        def collect(literals)
+          collect_details(literals)[:all]
+        end
+
+        # @param literals [Array<Object>]
+        # @return [Hash<Symbol, Array<String>>]
+        # :reek:TooManyStatements
+        def collect_details(literals)
+          reset
+          Array(literals).each { |literal| collect_from_literal(literal) }
+          explicit = explicit_names.uniq
+          unification = unify_names.uniq
+          { explicit: explicit, unification: unification, all: (explicit + unification).uniq }
+        end
+
+        private
+
+        attr_reader :explicit_names, :unify_names
+
+        def reset
+          explicit_names.clear
+          unify_names.clear
+        end
+
+        def collect_from_literal(literal)
+          case literal
+          in AST::SomeDecl[variables:]
+            variables.each { |variable| explicit_names << variable.name }
+          in AST::QueryLiteral[expression:]
+            collect_from_expression(expression)
+          else
+            nil
+          end
+        end
+
+        # :reek:FeatureEnvy
+        # :reek:TooManyStatements
+        def collect_from_expression(expression)
+          return unless expression.is_a?(AST::BinaryOp)
+
+          operator = expression.operator
+          left = expression.left
+          collect_explicit_variables(left) if operator == :assign
+          return unless operator == :unify
+
+          collect_unification_variables(left)
+          collect_unification_variables(expression.right)
+        end
+
+        def collect_explicit_variables(node)
+          collect_all_variables(node, explicit_names)
+        end
+
+        def collect_unification_variables(node)
+          collect_all_variables(node, unify_names)
+        end
+
+        # :reek:FeatureEnvy
+        def collect_all_variables(node, target)
+          return unless node
+          return target << node.name if node.is_a?(AST::Variable)
+          return if VariableCollectorHelpers.comprehension_node?(node)
+
+          VariableCollectorHelpers.children_for(node).each do |child|
+            collect_all_variables(child, target)
+          end
+        end
+      end
+
+      # Collects variable names referenced in expressions and query literals.
+      # :reek:TooManyMethods
+      class VariableCollector
+        def initialize
+          @names = [] # @type var @names: Array[String]
+          @local_scopes = [] # @type var @local_scopes: Array[Array[String]]
+        end
+
+        # @param node [Object]
+        # @return [Array<String>]
+        def collect(node)
+          collect_node(node)
+          names
+        end
+
+        # @param literals [Array<Object>]
+        # @return [Array<String>]
+        def collect_literals(literals)
+          Array(literals).each { |literal| collect_node(literal) }
+          names
+        end
+
+        private
+
+        attr_reader :names
+
+        def collect_node(node)
+          return unless node
+
+          handler = VariableCollectorHelpers.collector_for(node)
+          return handler.call(node, self) if handler
+
+          VariableCollectorHelpers.children_for(node).each { |child| collect_node(child) }
+        end
+
+        def collect_comprehension(term_nodes, body_literals)
+          locals = BoundVariableCollector.new.collect(body_literals)
+          with_locals(locals) { collect_comprehension_body(term_nodes, body_literals) }
+        end
+
+        def collect_comprehension_body(term_nodes, body_literals)
+          term_nodes.each { |term_node| collect_node(term_node) }
+          Array(body_literals).each { |literal| collect_node(literal) }
+        end
+
+        def collect_some_decl(node)
+          node.variables.each { |variable| add_name(variable.name) }
+          collection = node.collection
+          collect_node(collection) if collection
+        end
+
+        # :reek:TooManyStatements
+        def collect_every(node)
+          collect_node(node.domain)
+          body = Array(node.body)
+          locals = BoundVariableCollector.new.collect(body)
+          locals.concat(every_variable_names(node))
+          with_locals(locals.uniq) { body.each { |literal| collect_node(literal) } }
+        end
+
+        # :reek:UtilityFunction
+        def every_variable_names(node)
+          [node.key_var, node.value_var].compact.map(&:name)
+        end
+
+        def add_name(name)
+          return if local_name?(name)
+
+          names << name
+        end
+
+        def with_locals(names)
+          @local_scopes << names
+          yield
+        ensure
+          @local_scopes.pop
+        end
+
+        def local_name?(name)
+          @local_scopes.any? { |scope| scope.include?(name) }
+        end
+      end
+    end
+  end
+end

data/lib/ruby/rego/evaluator.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require_relative "ast"
+require_relative "environment"
+require_relative "errors"
+require_relative "result"
+require_relative "value"
+require_relative "unifier"
+require_relative "compiled_module"
+require_relative "compiler"
+require_relative "evaluator/operator_evaluator"
+require_relative "evaluator/assignment_support"
+require_relative "evaluator/binding_helpers"
+require_relative "evaluator/expression_dispatch"
+require_relative "evaluator/object_literal_evaluator"
+require_relative "evaluator/comprehension_evaluator"
+require_relative "evaluator/rule_value_provider"
+require_relative "evaluator/reference_resolver"
+require_relative "evaluator/reference_key_resolver"
+require_relative "evaluator/expression_evaluator"
+require_relative "evaluator/variable_collector"
+require_relative "evaluator/rule_evaluator"
+require_relative "evaluator/query_node_builder"
+require_relative "with_modifiers/with_modifier"
+require_relative "with_modifiers/with_modifier_applier"
+
+module Ruby
+  module Rego
+    # Evaluates compiled Rego modules against input and data.
+    class Evaluator
+      # Builds an evaluator with a preconfigured environment.
+      #
+      # @param compiled_module [#rules_by_name, #package_path] compiled module
+      # @param environment [Environment] preconfigured environment
+      # @return [Evaluator]
+      def self.from_environment(compiled_module, environment)
+        evaluator = allocate
+        evaluator.send(:initialize_with_environment, compiled_module, environment)
+        evaluator
+      end
+
+      # Build an evaluator directly from an AST module.
+      #
+      # @param ast_module [AST::Module] parsed module
+      # @param options [Hash] evaluator options (input, data, compiler)
+      # @return [Evaluator] evaluator instance
+      def self.from_ast(ast_module, options = {})
+        default_input = {} # @type var default_input: Hash[untyped, untyped]
+        default_data = {} # @type var default_data: Hash[untyped, untyped]
+        options = { input: default_input, data: default_data, compiler: Compiler.new }.merge(options)
+        new(options[:compiler].compile(ast_module), input: options[:input], data: options[:data])
+      end
+
+      # Create an evaluator for a compiled module.
+      #
+      # @param compiled_module [#rules_by_name, #package_path] compiled module
+      # @param input [Object] input document
+      # @param data [Object] data document
+      def initialize(compiled_module, input: {}, data: {})
+        @compiled_module = compiled_module
+        rules_by_name = compiled_module.rules_by_name
+        package_path = compiled_module.package_path
+        @environment = Environment.new(input: input, data: data, rules: rules_by_name)
+        @expression_evaluator, @rule_evaluator = build_evaluators(rules_by_name, package_path)
+      end
+
+      # The compiled module being evaluated.
+      #
+      # @return [#rules_by_name, #package_path]
+      attr_reader :compiled_module
+
+      # The environment used to evaluate expressions and rules.
+      #
+      # @return [Environment]
+      attr_reader :environment
+
+      # Evaluate either a query path or all rules.
+      #
+      # @param query [Object, nil] query path (e.g. "data.package.rule")
+      # @return [Result] evaluation result
+      def evaluate(query = nil)
+        environment.memoization.reset!
+        value, bindings = query ? evaluate_query(query) : [evaluate_rules, nil]
+        ResultBuilder.new(value, bindings).build
+      end
+
+      private
+
+      attr_reader :expression_evaluator, :rule_evaluator
+
+      def build_evaluators(rules_by_name, package_path)
+        rule_value_provider = RuleValueProvider.new(
+          rules_by_name: rules_by_name,
+          memoization: environment.memoization
+        )
+        expression_evaluator = build_expression_evaluator(rule_value_provider, package_path)
+        rule_evaluator = build_rule_evaluator(expression_evaluator, rule_value_provider)
+        expression_evaluator.attach_query_evaluator(rule_evaluator)
+        [expression_evaluator, rule_evaluator]
+      end
+
+      def build_expression_evaluator(rule_value_provider, package_path)
+        ExpressionEvaluator.new(
+          environment: @environment,
+          reference_resolver: ReferenceResolver.new(
+            environment: @environment,
+            package_path: package_path,
+            rule_value_provider: rule_value_provider,
+            imports: compiled_module.imports,
+            memoization: environment.memoization
+          )
+        )
+      end
+
+      def build_rule_evaluator(expression_evaluator, rule_value_provider)
+        RuleEvaluator.new(
+          environment: @environment,
+          expression_evaluator: expression_evaluator
+        ).tap { |evaluator| rule_value_provider.attach(evaluator) }
+      end
+
+      def evaluate_rules
+        results = {} # @type var results: Hash[String, Value]
+        environment.rules.each do |name, rules|
+          results[name] = rule_evaluator.evaluate_group(rules)
+        end
+        results
+      end
+
+      def evaluate_query(query)
+        node = QueryNodeBuilder.new(query).build
+        bindings = bindings_for_query(node)
+        value = expression_evaluator.evaluate(node)
+        [value, bindings]
+      end
+
+      def bindings_for_query(node)
+        expression_evaluator.eval_with_unification(node, environment).first || {}
+      end
+
+      def eval_node(node)
+        expression_evaluator.evaluate(node)
+      end
+
+      def initialize_with_environment(compiled_module, environment)
+        @compiled_module = compiled_module
+        rules_by_name = compiled_module.rules_by_name
+        package_path = compiled_module.package_path
+        @environment = environment
+        @expression_evaluator, @rule_evaluator = build_evaluators(rules_by_name, package_path)
+      end
+      private :initialize_with_environment
+    end
+
+    # Builds result objects from evaluation outputs.
+    class ResultBuilder
+      def initialize(value, bindings)
+        @value = value
+        @bindings = bindings
+      end
+
+      def build
+        success = !value.is_a?(UndefinedValue)
+        return Result.new(value: value, success: success) unless bindings
+
+        Result.new(value: value, success: success, bindings: bindings)
+      end
+
+      private
+
+      attr_reader :bindings, :value
+    end
+  end
+end

data/lib/ruby/rego/lexer/number_reader.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Ruby
+  module Rego
+    # Lexer helpers for numeric literals.
+    class Lexer
+      private
+
+      def read_number
+        start = capture_position
+        buffer = read_number_prefix
+        buffer << read_fractional_part
+        buffer << read_exponent_part
+        build_token(TokenType::NUMBER, parse_number(buffer, start), start)
+      end
+
+      def read_number_prefix
+        buffer = +""
+        buffer << advance
+        raise_error("Invalid number literal", capture_position, length: 1) if buffer == "0" && digit?(current_char)
+        buffer << read_digits
+        buffer
+      end
+
+      def read_fractional_part
+        return "" unless current_char == "."
+
+        raise_error("Invalid number literal", capture_position, length: 1) unless digit?(peek(1))
+        buffer = +""
+        buffer << advance
+        buffer << read_digits
+        buffer
+      end
+
+      def read_exponent_part
+        return "" unless exponent_start?
+
+        buffer = +""
+        buffer << advance
+        buffer << read_exponent_sign
+        raise_error("Invalid number exponent", capture_position, length: 1) unless digit?(current_char)
+        buffer << read_digits
+        buffer
+      end
+
+      def read_exponent_sign
+        sign = current_char
+        return "" unless sign && SIGN_CHARS.include?(sign)
+
+        advance
+      end
+
+      def read_digits
+        digits = +""
+        digits << advance while digit?(current_char)
+        digits
+      end
+
+      def parse_number(buffer, start)
+        return Float(buffer) if buffer.include?(".") || buffer.match?(/[eE]/)
+
+        Integer(buffer, 10)
+      rescue ArgumentError
+        raise_error("Invalid number literal", start, length: buffer.length)
+      end
+    end
+  end
+end

data/lib/ruby/rego/lexer/stream.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module Ruby
+  module Rego
+    # Stream helpers for lexer traversal and errors.
+    # :reek:InstanceVariableAssumption
+    class Lexer
+      private
+
+      def advance
+        char = current_char
+        raise_unexpected_eof if char.nil?
+
+        return advance_line_break if char == "\r"
+        return advance_newline if char == "\n"
+
+        increment_position(1)
+        char
+      end
+
+      def advance_line_break
+        increment_line(peek == "\n" ? 2 : 1)
+        "\n"
+      end
+
+      def advance_newline
+        increment_line(1)
+        "\n"
+      end
+
+      def increment_line(count)
+        @position += count
+        @offset += count
+        @line += 1
+        @column = 1
+      end
+
+      def increment_position(count)
+        @position += count
+        @offset += count
+        @column += count
+      end
+
+      def peek(distance = 1)
+        source[@position + distance]
+      end
+
+      def match?(expected)
+        return false unless current_char == expected
+
+        advance
+        true
+      end
+
+      def current_char
+        source[@position]
+      end
+
+      def eof?
+        @position >= source.length
+      end
+
+      def capture_position
+        { line: line, column: column, offset: offset }
+      end
+
+      def build_token(type, value, start)
+        start_offset = start.fetch(:offset) || 0
+        length = offset - start_offset
+        location = Location.new(
+          line: start.fetch(:line),
+          column: start.fetch(:column),
+          offset: start_offset,
+          length: length
+        )
+        Token.new(type: type, value: value, location: location)
+      end
+
+      def identifier_start?(char)
+        !!(char && char.match?(IDENTIFIER_START))
+      end
+
+      def identifier_part?(char)
+        !!(char && char.match?(IDENTIFIER_PART))
+      end
+
+      def digit?(char)
+        !!(char && char.match?(DIGIT))
+      end
+
+      def hex_digit?(char)
+        !!(char && char.match?(HEX_DIGIT))
+      end
+
+      def whitespace?(char)
+        return false if char.nil?
+
+        WHITESPACE_CHARS.include?(char)
+      end
+
+      def newline?(char)
+        return false if char.nil?
+
+        NEWLINE_CHARS.include?(char)
+      end
+
+      def exponent_start?
+        char = current_char
+        !!(char && EXPONENT_CHARS.include?(char))
+      end
+
+      def span_length_from(start)
+        start_offset = start.fetch(:offset) || 0
+        offset - start_offset
+      end
+
+      def raise_unterminated_string(start)
+        raise_error("Unterminated string literal", start, length: span_length_from(start))
+      end
+
+      def raise_unterminated_raw_string(start)
+        raise_error("Unterminated raw string literal", start, length: span_length_from(start))
+      end
+
+      def raise_unexpected_eof
+        raise_error("Unexpected end of input", capture_position, length: 0)
+      end
+
+      def raise_error(message, position, length: nil)
+        line_value = position.fetch(:line)
+        column_value = position.fetch(:column)
+        offset_value = position.fetch(:offset) || 0
+        raise LexerError.new(message, line: line_value, column: column_value, offset: offset_value, length: length)
+      end
+    end
+  end
+end

data/lib/ruby/rego/lexer/string_reader.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Ruby
+  module Rego
+    # Lexer helpers for string literals.
+    class Lexer
+      TEMPLATE_ESCAPE = "\u0000"
+
+      private
+
+      # rubocop:disable Metrics/MethodLength
+      def read_string
+        start = capture_position
+        advance
+        buffer = +""
+        until eof?
+          char_position = capture_position
+          char = advance
+          return build_token(TokenType::STRING, buffer, start) if char == "\""
+
+          break if char == "\n"
+
+          buffer << (char == "\\" ? read_escape_sequence(char_position) : char)
+        end
+        raise_unterminated_string(start)
+      end
+
+      def read_raw_string
+        start = capture_position
+        advance
+        buffer = +""
+        until eof?
+          char = advance
+          return build_token(TokenType::RAW_STRING, buffer, start) if char == "`"
+
+          if char == "\\" && current_char == "{"
+            advance
+            buffer << "{"
+          else
+            buffer << char
+          end
+        end
+        raise_unterminated_raw_string(start)
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      # rubocop:disable Metrics/MethodLength, Metrics/CyclomaticComplexity
+      def read_escape_sequence(backslash_position)
+        char = current_char
+        raise_unterminated_string(backslash_position) if char.nil? || char == "\n"
+
+        advance
+
+        case char
+        when "\"", "\\", "/", "{"
+          char
+        when "b"
+          "\b"
+        when "f"
+          "\f"
+        when "n"
+          "\n"
+        when "r"
+          "\r"
+        when "t"
+          "\t"
+        when "u"
+          read_unicode_escape
+        else
+          raise_error("Invalid escape sequence: \\#{char}", backslash_position, length: 2)
+        end
+      end
+      # rubocop:enable Metrics/MethodLength, Metrics/CyclomaticComplexity
+
+      def read_unicode_escape
+        hex = +""
+
+        4.times do
+          char = current_char.to_s
+          raise_error("Invalid unicode escape sequence", capture_position, length: 1) unless hex_digit?(char)
+
+          advance
+          hex << char
+        end
+
+        [hex.to_i(16)].pack("U")
+      end
+    end
+  end
+end