lex-react 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 77b98f390c59e0768be5c629e704e3d5920297695a78fa114481a8fe5b89e9ac
+  data.tar.gz: b48f8e5959e929359661b2e4fe206ca65fa0d1e189a1c3628a403bfa142cfcf3
+SHA512:
+  metadata.gz: 8608c662d7654352d1cd4222307ef6749f2ad916ca0a92a20ead94ad8cc28650e3f8f4a8e13a3c3f4f105b4d387afb4e087ef88cad8eecb5150bb2097d8a4e3c
+  data.tar.gz: c9b7db15123922391729970bd08d38d1208514115369b5f4ebc170e2f78d4576b5c3d52cf9985836804055c4ab858ef79d483395fac23ef344ccc0b50d14216f

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## [0.1.0] - 2026-03-24
+
+### Added
+- Initial release: rule engine, event matcher, reaction dispatcher, loop breaker
+- Wildcard event subscription via Legion::Events
+- YAML-based configurable reaction rules via Legion::Settings
+- Synapse autonomy level gating (OBSERVE/FILTER/TRANSFORM/AUTONOMOUS)
+- Loop prevention with configurable depth limit and cooldown window

data/README.md

@@ -0,0 +1,29 @@
+# lex-react
+
+Reaction engine for LegionIO. Subscribes to `Legion::Events` and fires configurable reaction chains in response to events, with Synapse autonomy gating and loop prevention.
+
+## Configuration
+
+```yaml
+react:
+  rules:
+    ci_failure:
+      enabled: true
+      source: "github.check_run.completed"
+      condition: "conclusion == 'failure'"
+      autonomy: FILTER
+      chain:
+        - lex-github.runners.fetch_check_logs
+        - lex-transformer.runners.analyze
+  max_depth: 3
+  cooldown_seconds: 60
+  max_reactions_per_hour: 100
+```
+
+## Usage
+
+lex-react auto-subscribes to `Legion::Events` on extension load. Rules are evaluated against every event. Matching rules dispatch task chains respecting Synapse autonomy levels.
+
+## License
+
+MIT

data/lib/legion/extensions/react/actors/event_subscriber.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module React
+      module Actor
+        class EventSubscriber < Legion::Extensions::Actors::Once
+          def runner_class    = 'Legion::Extensions::React'
+          def runner_function = 'subscribe!'
+          def check_subtask?  = false
+          def generate_task?  = false
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/react/helpers/constants.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module React
+      module Helpers
+        module Constants
+          AUTONOMY_LEVELS = %i[observe filter transform autonomous].freeze
+
+          AUTONOMY_THRESHOLDS = {
+            observe:    0.0,
+            filter:     0.3,
+            transform:  0.6,
+            autonomous: 0.8
+          }.freeze
+
+          DEFAULT_MAX_DEPTH              = 3
+          DEFAULT_COOLDOWN_SECONDS       = 60
+          DEFAULT_MAX_REACTIONS_PER_HOUR = 100
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/react/helpers/event_matcher.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module React
+      module Helpers
+        module EventMatcher
+          module_function
+
+          def match?(pattern, event_name)
+            # Use placeholder so '.**' double-star replacement isn't re-processed by single '*' gsub
+            regex_str = pattern.gsub('.**', '__DS__')
+                               .gsub('*', '[^.]*')
+                               .gsub('__DS__', '\..*')
+            regex_str = "\\A#{regex_str}\\z"
+            Regexp.new(regex_str).match?(event_name)
+          rescue RegexpError
+            false
+          end
+
+          def evaluate_condition(condition, event)
+            return true if condition.nil? || condition.strip.empty?
+
+            # Parse simple conditions: "key == 'value'" or "key != 'value'"
+            if condition =~ /\A(\w+)\s*(==|!=)\s*'([^']*)'\z/
+              key    = Regexp.last_match(1).to_sym
+              op     = Regexp.last_match(2)
+              value  = Regexp.last_match(3)
+              actual = event[key]&.to_s
+
+              case op
+              when '==' then actual == value
+              when '!=' then actual != value
+              else false
+              end
+            else
+              false
+            end
+          rescue StandardError
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/react/helpers/loop_breaker.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module React
+      module Helpers
+        class LoopBreaker
+          def initialize(max_depth: Constants::DEFAULT_MAX_DEPTH,
+                         cooldown_seconds: Constants::DEFAULT_COOLDOWN_SECONDS,
+                         max_per_hour: Constants::DEFAULT_MAX_REACTIONS_PER_HOUR)
+            @max_depth        = max_depth
+            @cooldown_seconds = cooldown_seconds
+            @max_per_hour     = max_per_hour
+            @recent           = [] # Array of { rule_id:, event_id:, at: }
+            @mutex            = Mutex.new
+          end
+
+          def allow?(rule_id:, depth:, event_id: nil)
+            return false if depth > @max_depth
+
+            @mutex.synchronize do
+              prune_old_entries
+              return false if @recent.size >= @max_per_hour
+
+              if event_id && @cooldown_seconds.positive?
+                duplicate = @recent.any? do |r|
+                  r[:rule_id] == rule_id && r[:event_id] == event_id
+                end
+                return false if duplicate
+              end
+
+              true
+            end
+          end
+
+          def record(rule_id:, event_id:)
+            @mutex.synchronize do
+              @recent << { rule_id: rule_id, event_id: event_id, at: Time.now }
+            end
+          end
+
+          def reactions_this_hour
+            @mutex.synchronize do
+              prune_old_entries
+              @recent.size
+            end
+          end
+
+          def stats
+            @mutex.synchronize do
+              prune_old_entries
+              { reactions_this_hour: @recent.size, max_per_hour: @max_per_hour }
+            end
+          end
+
+          private
+
+          def prune_old_entries
+            cutoff = Time.now - 3600
+            @recent.reject! { |r| r[:at] < cutoff }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/react/reaction_dispatcher.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module React
+      class ReactionDispatcher
+        def initialize(loop_breaker:)
+          @loop_breaker = loop_breaker
+        end
+
+        def dispatch(rule:, event:, depth: 0)
+          event_id = event[:event].to_s
+
+          unless @loop_breaker.allow?(rule_id: rule[:id].to_s, depth: depth, event_id: event_id)
+            log_blocked(rule, event)
+            return { success: false, rule_id: rule[:id], reason: :loop_blocked }
+          end
+
+          if rule[:autonomy] == :observe
+            log_observed(rule, event)
+            return { success: true, rule_id: rule[:id], action: :observed, chain: rule[:chain] }
+          end
+
+          execute_chain(rule, event)
+          @loop_breaker.record(rule_id: rule[:id].to_s, event_id: event_id)
+
+          { success: true, rule_id: rule[:id], action: :dispatched, chain: rule[:chain] }
+        rescue StandardError => e
+          { success: false, rule_id: rule[:id], error: e.message }
+        end
+
+        private
+
+        def execute_chain(rule, event)
+          rule[:chain].each do |runner_ref|
+            dispatch_runner(runner_ref, event, rule)
+          end
+        end
+
+        def dispatch_runner(runner_ref, event, rule)
+          Legion::Events.emit('react.dispatched',
+                              rule_id:      rule[:id],
+                              runner_ref:   runner_ref,
+                              source_event: event[:event],
+                              autonomy:     rule[:autonomy])
+        rescue StandardError => e
+          Legion::Logging.warn "[React] dispatch error: #{e.message}" if defined?(Legion::Logging)
+        end
+
+        def log_observed(rule, event)
+          return unless defined?(Legion::Logging)
+
+          Legion::Logging.info "[React] OBSERVE rule=#{rule[:id]} event=#{event[:event]} chain=#{rule[:chain]}"
+        end
+
+        def log_blocked(rule, event)
+          return unless defined?(Legion::Logging)
+
+          Legion::Logging.warn "[React] BLOCKED rule=#{rule[:id]} event=#{event[:event]} (loop prevention)"
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/react/rule_engine.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module React
+      class RuleEngine
+        attr_reader :rules
+
+        def initialize(rules_hash = {})
+          @rules = parse_rules(rules_hash)
+        end
+
+        def self.from_settings
+          rules_hash = if defined?(Legion::Settings) && !Legion::Settings[:react].nil?
+                         Legion::Settings.dig(:react, :rules) || {}
+                       else
+                         {}
+                       end
+          new(rules_hash)
+        rescue StandardError
+          new({})
+        end
+
+        def match(event)
+          event_name = event[:event].to_s
+          @rules.select do |rule|
+            Helpers::EventMatcher.match?(rule[:source], event_name) &&
+              Helpers::EventMatcher.evaluate_condition(rule[:condition], event)
+          end
+        end
+
+        private
+
+        def parse_rules(rules_hash)
+          rules_hash.filter_map do |id, config|
+            next unless config.is_a?(Hash) && config[:enabled] != false
+
+            {
+              id:        id.to_sym,
+              source:    config[:source].to_s,
+              condition: config[:condition],
+              autonomy:  (config[:autonomy] || 'observe').to_s.downcase.to_sym,
+              chain:     Array(config[:chain])
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/react/runners/react.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module React
+      module Runners
+        module React
+          module_function
+
+          def handle_event(event:)
+            engine     = rule_engine
+            matches    = engine.match(event)
+            dispatcher = reaction_dispatcher
+
+            results = matches.map do |rule|
+              dispatcher.dispatch(rule: rule, event: event, depth: event[:react_depth] || 0)
+            end
+
+            {
+              success:       true,
+              matched_rules: matches.size,
+              results:       results
+            }
+          rescue StandardError => e
+            { success: false, error: e.message }
+          end
+
+          def react_stats
+            engine        = rule_engine
+            breaker_stats = loop_breaker.stats
+
+            {
+              success:             true,
+              rule_count:          engine.rules.size,
+              reactions_this_hour: breaker_stats[:reactions_this_hour],
+              max_per_hour:        breaker_stats[:max_per_hour]
+            }
+          rescue StandardError => e
+            { success: false, error: e.message }
+          end
+
+          def reset!
+            @rule_engine         = nil
+            @loop_breaker        = nil
+            @reaction_dispatcher = nil
+          end
+
+          def rule_engine
+            @rule_engine ||= RuleEngine.from_settings
+          end
+
+          def loop_breaker
+            @loop_breaker ||= begin
+              settings = react_settings
+              Helpers::LoopBreaker.new(
+                max_depth:        settings[:max_depth] || Helpers::Constants::DEFAULT_MAX_DEPTH,
+                cooldown_seconds: settings[:cooldown_seconds] || Helpers::Constants::DEFAULT_COOLDOWN_SECONDS,
+                max_per_hour:     settings[:max_reactions_per_hour] || Helpers::Constants::DEFAULT_MAX_REACTIONS_PER_HOUR
+              )
+            end
+          end
+
+          def reaction_dispatcher
+            @reaction_dispatcher ||= ReactionDispatcher.new(loop_breaker: loop_breaker)
+          end
+
+          def react_settings
+            return {} unless defined?(Legion::Settings) && !Legion::Settings[:react].nil?
+
+            Legion::Settings[:react] || {}
+          rescue StandardError
+            {}
+          end
+
+          private_class_method :rule_engine, :loop_breaker, :reaction_dispatcher, :react_settings
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/react/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module React
+      VERSION = '0.1.0'
+    end
+  end
+end

data/lib/legion/extensions/react.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/react/version'
+require_relative 'react/helpers/constants'
+require_relative 'react/helpers/event_matcher'
+require_relative 'react/helpers/loop_breaker'
+require_relative 'react/rule_engine'
+require_relative 'react/reaction_dispatcher'
+require_relative 'react/runners/react'
+
+module Legion
+  module Extensions
+    module React
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined?(:Core)
+
+      class << self
+        def data_required?
+          false
+        end
+
+        def subscribe!
+          return unless defined?(Legion::Events)
+
+          @subscription ||= Legion::Events.on('*') do |event|
+            next if event[:event].to_s.start_with?('react.')
+
+            Runners::React.handle_event(event: event)
+          rescue StandardError => e
+            Legion::Logging.warn "[React] event handler error: #{e.message}" if defined?(Legion::Logging)
+          end
+        end
+
+        def unsubscribe!
+          return unless @subscription && defined?(Legion::Events)
+
+          Legion::Events.off('*', @subscription)
+          @subscription = nil
+        end
+      end
+
+      require_relative 'react/actors/event_subscriber' if defined?(Legion::Extensions::Actors::Once)
+    end
+  end
+end

metadata

@@ -0,0 +1,53 @@
+--- !ruby/object:Gem::Specification
+name: lex-react
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Esity
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Event-driven automation rules that subscribe to Legion::Events and fire
+  configurable reaction chains
+email:
+- legionio@esity.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- README.md
+- lib/legion/extensions/react.rb
+- lib/legion/extensions/react/actors/event_subscriber.rb
+- lib/legion/extensions/react/helpers/constants.rb
+- lib/legion/extensions/react/helpers/event_matcher.rb
+- lib/legion/extensions/react/helpers/loop_breaker.rb
+- lib/legion/extensions/react/reaction_dispatcher.rb
+- lib/legion/extensions/react/rule_engine.rb
+- lib/legion/extensions/react/runners/react.rb
+- lib/legion/extensions/react/version.rb
+homepage: https://github.com/LegionIO/lex-react
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Reaction engine for LegionIO
+test_files: []