buzz_logic 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cc4c70ca95e3e3e8eed36b92f72f2668f7b5c05a1b0599b930e8caa84983bbd4
+  data.tar.gz: e073cd8be81197b5c3f418e0b6a2abaada5c8b3f665268c86e150a65aaed23a9
+SHA512:
+  metadata.gz: 1ec7200ccb43f8fa26c63b30eb2ca5350d27c7308a7ab0bf9d0b15e829398d4bd1bbc8bfbd22d62f4c26b8ac6ef50f433df08e3c02ea35422f3e4d331b4be954
+  data.tar.gz: d753ba2cafb0636f904a6930d178de911794c9a14b0ba8c9e94fb2fd8b49c0a6235e27e0a161053f74c52028da5b21501d3060714928152105e144d93988cc4b

data/.rubocop.yml

@@ -0,0 +1,8 @@
+# Omakase Ruby styling for Rails
+inherit_gem: { rubocop-rails-omakase: rubocop.yml }
+
+# Overwrite or add rules to create your own house style
+#
+# # Use `[a, [b, c]]` not `[ a, [ b, c ] ]`
+# Layout/SpaceInsideArrayLiteralBrackets:
+#   Enabled: false

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Buzz Logic - Change Log
+
+## [1.0.0] - 2025-06-16
+
+- First version of BuzzLogic, extracted from FutureFund.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 FutureFund Technology, LLC.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,109 @@
+# BuzzLogic Rules Engine
+
+Welcome to BuzzLogic, the rules engine that brings the power of dynamic, secure logic to your hive! Built by FutureFund for our online platform for K-12 school groups and PTAs, BuzzLogic makes it easy to evaluate rules without exposing your application to security risks.
+
+It's the bee's knees for handling logic.
+
+## Features
+
+- Dynamic Rules: Define rules as simple strings (e.g., `user.age >= 21 and fundraiser.status == 'active'`).
+- Secure by Design: Uses a custom parser and interpreter, avoiding `eval()` and other unsafe methods. Only allows predefined operations, keeping your hive safe.
+- Context-Aware: Evaluate rules against a context of one or more objects from your application.
+- Rich Operator Support: Includes standard comparison (`==`, `!=`, `<`, `>`, `<=`, `>=`) and logical (`and`, `or`) operators.
+- Nested Attribute Access: Safely access nested object attributes (e.g., `user.school.mascot`).
+- Extensible: Designed to be easy to extend with custom functions or operators.
+- Thoroughly Tested: Comes with a comprehensive Minitest test suite.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```
+gem "buzz_logic"
+```
+
+And then execute:
+
+```
+$ bundle install
+```
+
+Or install it yourself as:
+
+```
+$ gem install buzz_logic
+```
+
+## Usage
+
+The primary interface for the engine is the BuzzLogic::RulesEngine.evaluate method. It takes two arguments:
+
+- `rule_string` (String): The rule you want to evaluate.
+- `context` (Hash): A hash where keys are the names used in the rule (the "buzz words") and values are the corresponding objects.
+
+### Basic Example
+
+```ruby
+require 'buzz_logic'
+
+# Define some objects to evaluate against
+student = OpenStruct.new(grade: 5, has_permission_slip: true)
+fundraiser = OpenStruct.new(status: 'active', goal_amount: 500)
+
+# The context maps the names used in the rule to the objects
+context = {
+  'student' => student,
+  'fundraiser' => fundraiser
+}
+
+# Define a rule
+rule = "student.grade >= 4 and fundraiser.status == 'active'"
+
+# Evaluate the rule
+result = BuzzLogic::RulesEngine.evaluate(rule, context)
+
+puts "Is the student eligible? #{result}" # => true
+```
+
+## Supported Syntax
+
+### Operands
+
+- Literals:
+  - `String`: e.g., 'active', "Go Bees!"
+  - `Integer`: e.g., 5, 1000
+  - `Float`: e.g., 99.9
+  - `Boolean`: true, false
+  - `Nil`: nil
+- Variables: Access object attributes using dot notation.
+  - `student.grade`
+  - `fundraiser.school.principal_name`
+
+### Operators
+
+- Comparison: `==`, `!=`, `<`, `<=`, `>`, `>=`
+- Logical: `and`, `or`
+
+Parentheses `()` can be used to group expressions and control precedence.
+
+### Security
+
+Security is the queen bee of BuzzLogic's design. Unlike approaches that use eval, BuzzLogic parses the rule into an Abstract Syntax Tree (AST) and then interprets it.
+
+This means:
+
+- **No Arbitrary Code Execution:** A rule like `system('rm -rf /')` will result in a parsing error, not a swarm of problems.
+- **No Unsafe Method Calls:** A rule like `student.destroy` is impossible. The interpreter only allows attribute access on the provided context objects, not method calls.
+
+## Development
+After checking out the repo, run `bundle install` to install dependencies. Then, run `rake test` to run the tests.
+
+To install this gem onto your local machine, run bundle exec `rake install`.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub. Let's build a sweeter future together!
+
+## License
+
+The gem is available as open source under the terms of the MIT License by FutureFund.

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task default: :test

data/lib/buzz_logic/engine.rb

@@ -0,0 +1,181 @@
+require "strscan"
+
+module BuzzLogic
+  # The internal engine that parses and evaluates rules.
+  # This class is not meant to be used directly. Use BuzzLogic::RulesEngine.evaluate instead.
+  class Engine
+    # Tokenizer patterns
+    TOKEN_PATTERNS = {
+      float: /-?\d+\.\d+/,
+      integer: /-?\d+/,
+      string: /'(?:[^']|\\.)*'|"(?:[^"]|\\.)*"/,
+      boolean: /true|false/,
+      nil: /nil/,
+      identifier: /[a-zA-Z_][a-zA-Z0-9_]*/,
+      operator: /==|!=|<=|>=|<|>/,
+      logical: /and|or/,
+      lparen: /\(/,
+      rparen: /\)/,
+      dot: /\./,
+      space: /\s+/
+    }.freeze
+
+    # Operator precedence for the parser
+    PRECEDENCE = {
+      "or" => 1,
+      "and" => 2,
+      "==" => 3, "!=" => 3,
+      "<" => 4, "<=" => 4, ">" => 4, ">=" => 4
+    }.freeze
+
+    def initialize(context)
+      @context = context
+      @tokens = []
+    end
+
+    # Primary method to evaluate a rule string.
+    def evaluate(rule_string)
+      @tokens = tokenize(rule_string)
+      ast = parse
+      raise ParsingError, "Invalid or empty rule." if ast.nil?
+      eval_ast(ast)
+    end
+
+    private
+
+    # Step 1: Tokenization
+    def tokenize(rule_string)
+      scanner = StringScanner.new(rule_string)
+      tokens = []
+      until scanner.eos?
+        match = nil
+        TOKEN_PATTERNS.each do |type, pattern|
+          if (match = scanner.scan(pattern))
+            tokens << { type: type, value: match } unless type == :space
+            break
+          end
+        end
+        raise ParsingError, "Unexpected character at: #{scanner.rest}" unless match || scanner.eos?
+      end
+      tokens
+    end
+
+    # Step 2: Parsing
+    def parse(precedence = 0)
+      left_node = parse_prefix
+      return nil unless left_node
+
+      while !@tokens.empty? && precedence < (PRECEDENCE[@tokens.first[:value]] || 0)
+        op_token = @tokens.shift
+        right_node = parse(PRECEDENCE[op_token[:value]])
+        left_node = { type: :binary_op, op: op_token[:value], left: left_node, right: right_node }
+      end
+
+      left_node
+    end
+
+    def parse_prefix
+      token = @tokens.shift
+      case token[:type]
+      when :integer, :float, :string, :boolean, :nil
+        parse_literal(token)
+      when :identifier
+        parse_variable(token)
+      when :lparen
+        parse_grouped_expression
+      else
+        raise ParsingError, "Unexpected token: #{token[:value]}"
+      end
+    end
+
+    def parse_literal(token)
+      value = token[:value]
+      case token[:type]
+      when :integer then { type: :literal, value: value.to_i }
+      when :float   then { type: :literal, value: value.to_f }
+      when :string  then { type: :literal, value: value[1..-2].gsub(/\\./, { "\\'" => "'", '\\"' => '"' }) }
+      when :boolean then { type: :literal, value: value == "true" }
+      when :nil     then { type: :literal, value: nil }
+      end
+    end
+
+    def parse_variable(token)
+      node = { type: :variable, name: token[:value] }
+      while !@tokens.empty? && @tokens.first[:type] == :dot
+        @tokens.shift # consume dot
+        attr_token = @tokens.shift
+        raise ParsingError, "Expected identifier after '.'" unless attr_token && attr_token[:type] == :identifier
+        node = { type: :attribute_access, object: node, attribute: attr_token[:value] }
+      end
+      node
+    end
+
+    def parse_grouped_expression
+      node = parse(0)
+      raise ParsingError, "Expected ')' to close expression" if @tokens.shift&.dig(:type) != :rparen
+      node
+    end
+
+    # Step 3: AST Evaluation
+    def eval_ast(node)
+      return node[:value] if node[:type] == :literal
+
+      case node[:type]
+      when :variable
+        resolve_variable(node[:name])
+      when :attribute_access
+        object = eval_ast(node[:object])
+        resolve_attribute(object, node[:attribute])
+      when :binary_op
+        left_val = eval_ast(node[:left])
+        return true if node[:op] == "or" && left_val
+        return false if node[:op] == "and" && !left_val
+        right_val = eval_ast(node[:right])
+        perform_operation(node[:op], left_val, right_val)
+      else
+        raise EvaluationError, "Unknown AST node type: #{node[:type]}"
+      end
+    end
+
+    def resolve_variable(name)
+      raise EvaluationError, "Undefined variable: '#{name}'" unless @context.key?(name)
+      @context[name]
+    end
+
+    def resolve_attribute(object, attribute)
+      raise EvaluationError, "Cannot access attribute on nil" if object.nil?
+
+      if object.respond_to?(attribute)
+        method = object.method(attribute)
+        if method.arity == 0
+          return method.call
+        else
+          raise EvaluationError, "Access to method '#{attribute}' with arguments is not allowed."
+        end
+      end
+
+      raise EvaluationError, "Cannot access '#{attribute}' on object of type #{object.class}"
+    rescue NoMethodError
+      raise EvaluationError, "Object does not have attribute '#{attribute}'"
+    rescue => e
+      raise EvaluationError, "An error occurred while accessing attribute '#{attribute}': #{e.message}"
+    end
+
+    def perform_operation(op, left, right)
+      case op
+      when "=="  then left == right
+      when "!="  then left != right
+      when "<"   then left < right
+      when "<="  then left <= right
+      when ">"   then left > right
+      when ">="  then left >= right
+      when "and" then !!(left && right)
+      when "or"  then !!(left || right)
+      else
+        raise EvaluationError, "Unknown operator: #{op}"
+      end
+    rescue ArgumentError => e
+      raise EvaluationError, "Type mismatch for operator '#{op}': #{e.message}"
+    end
+  end
+end

data/lib/buzz_logic/version.rb

@@ -0,0 +1,3 @@
+module BuzzLogic
+  VERSION = "1.0.0"
+end

data/lib/buzz_logic.rb

@@ -0,0 +1,24 @@
+require_relative "buzz_logic/version"
+require_relative "buzz_logic/engine"
+
+# Main module for the BuzzLogic Rules Engine from FutureFund.
+# The primary entry point is `BuzzLogic::RulesEngine.evaluate`.
+module BuzzLogic
+  class Error < StandardError; end
+  class ParsingError < Error; end
+  class EvaluationError < Error; end
+
+  # The main interface for the rules engine.
+  module RulesEngine
+    # Evaluates a given rule string against a context of objects.
+    #
+    # @param rule_string [String] The rule to evaluate.
+    # @param context [Hash<String, Object>] A hash mapping names to objects.
+    # @return [Boolean] The result of the evaluation.
+    # @raise [BuzzLogic::ParsingError] if the rule has invalid syntax.
+    # @raise [BuzzLogic::EvaluationError] if an error occurs during evaluation.
+    def self.evaluate(rule_string, context)
+      Engine.new(context).evaluate(rule_string)
+    end
+  end
+end

metadata

@@ -0,0 +1,58 @@
+--- !ruby/object:Gem::Specification
+name: buzz_logic
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Darian Shimy
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-06-17 00:00:00.000000000 Z
+dependencies: []
+description: BuzzLogic, created by FutureFund, allows dynamic rule evaluation against
+  application objects for platforms like our K-12 fundraising site. It avoids the
+  risks of arbitrary code execution by using a custom, secure parser.
+email:
+- dshimy@futurefund.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop.yml"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/buzz_logic.rb
+- lib/buzz_logic/engine.rb
+- lib/buzz_logic/version.rb
+homepage: https://github.com/futurefund/buzz_logic
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/futurefund/buzz_logic
+  source_code_uri: https://github.com/futurefund/buzz_logic
+  changelog_uri: https://github.com/FutureFund/buzz_logic/CHANGELOG.md
+  github_repo: ssh://github.com/FutureFund/buzz_logic
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.18
+signing_key:
+specification_version: 4
+summary: A simple, powerful, and secure rules engine for busy bees.
+test_files: []