reflekt 0.7.2 → 0.9.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d92d12a27556a25c258f83cf2983ffc2758a70c5cd359f4e7beafb862e88e68c
-  data.tar.gz: be5fa824eb0e6cd3bd15e03da504c40a65e471687881a5fbfcebc0d0906399fd
+  metadata.gz: f2048b61fdb7acc0deede9ee5bcae644e6d51fa6e2dab2842f748433ce5ba949
+  data.tar.gz: dce2b1bd92e2eaf90c16e1cad6c27d9b9fc686001c958124f184a5d11a2ebe8d
 SHA512:
-  metadata.gz: 9ffb39bc278932fd985731c7e509767e79c3356da41d7114a57cfe47a774bb97742ae283837859e2ff158ff84121e2b565c2bf25aff1ae0e8345671b9bd8da22
-  data.tar.gz: 3db51deab75140780e718e3536ab06696a1d0ef5308b1cbfcf2fb8a56dc9144905f22f2f53e918afcd7d1e962416134fc41a07676e17c4a16b935c70aece19fb
+  metadata.gz: b4bdebf8083aef0a50806c1970b25f90736dfe68b8373f5a742ef6c7f2e4139e4ca0d273d683d826230069de2039c5fda7428c4ed8147471da00f1e93704f59a
+  data.tar.gz: afbe22e05eb10efe8ead84240c4296546e10570c19e73efea912494e55a85538c8fbed2872c42485ea21ba696a101347e73ec5feee37a568636a154dcae8bcf6

data/lib/Accessor.rb

@@ -0,0 +1,37 @@
+################################################################################
+# ACCESSOR
+#
+# Access variables via one object to avoid polluting the caller class.
+#
+# Only 2 variables are not accessed via Accessor:
+#   - @reflection_counts on the instance
+#   - @@reflekt_skipped_methods on the instance's singleton class
+################################################################################
+
+class Accessor
+
+  attr_accessor :setup
+  attr_accessor :db
+  attr_accessor :stack
+  attr_accessor :renderer
+  attr_accessor :rules
+  attr_accessor :path
+  attr_accessor :output_path
+  attr_accessor :reflect_amount
+  attr_accessor :reflection_limit
+
+  def initialize()
+
+    @setup = nil
+    @db = nil
+    @stack = nil
+    @renderer = nil
+    @rules = nil
+    @path = nil
+    @output_path = nil
+    @reflect_amount = nil
+    @reflection_limit = nil
+
+  end
+
+end

data/lib/Control.rb

@@ -0,0 +1,33 @@
+require 'Reflection'
+
+class Control < Reflection
+
+  ##
+  # Reflect on a method.
+  #
+  # Creates a shadow execution stack.
+  #
+  # @param method - The name of the method.
+  # @param *args - The method arguments.
+  #
+  # @return - A reflection hash.
+  ##
+  def reflect(*args)
+
+    @inputs = *args
+
+    # Action method with new arguments.
+    begin
+      @output = @clone.send(@method, *@inputs)
+    # When fail.
+    rescue StandardError => message
+      @status = FAIL
+      @message = message
+    # When pass.
+    else
+      @status = PASS
+    end
+
+  end
+
+end

data/lib/Execution.rb

@@ -0,0 +1,47 @@
+class Execution
+
+  attr_accessor :object
+  attr_accessor :caller_id
+  attr_accessor :caller_class
+  attr_accessor :parent
+  attr_accessor :child
+  attr_accessor :control
+  attr_accessor :reflections
+  attr_accessor :is_reflecting
+
+  def initialize(object, reflection_count)
+
+    @object = object
+    @caller_id = object.object_id
+    @caller_class = object.class
+    @parent = nil
+    @child = nil
+
+    @control = []
+    @reflections = Array.new(reflection_count)
+    @is_reflecting = false
+
+  end
+
+  def has_empty_reflections?
+    @reflections.include? nil
+  end
+
+  ##
+  # Is the Execution currently reflecting methods?
+  ##
+  def is_reflecting?
+    @is_reflecting
+  end
+
+  def has_finished_reflecting?
+    if is_reflecting?
+      return false
+    end
+    if has_empty_reflections?
+      return false
+    end
+    return true
+  end
+
+end

data/lib/Reflection.rb

@@ -0,0 +1,163 @@
+class Reflection
+
+  # Keys.
+  TIME    = "t"
+  INPUT   = "i"
+  OUTPUT  = "o"
+  TYPE    = "T"
+  COUNT   = "C"
+  VALUE   = "V"
+  STATUS  = "s"
+  MESSAGE = "m"
+  # Values.
+  PASS    = "p"
+  FAIL    = "f"
+
+  attr_accessor :clone
+
+  def initialize(execution, method, ruler)
+
+    @execution = execution
+    @method = method
+    @ruler = ruler
+
+    # Clone the execution's object.
+    @clone = execution.object.clone
+    @clone_id = nil
+
+    # Result.
+    @status = nil
+    @time = Time.now.to_i
+    @inputs = []
+    @output = nil
+
+  end
+
+  ##
+  # Reflect on a method.
+  #
+  # Creates a shadow execution stack.
+  #
+  # @param method - The name of the method.
+  # @param *args - The method arguments.
+  #
+  # @return - A reflection hash.
+  ##
+  def reflect(*args)
+
+    # Create deviated arguments.
+    args.each do |arg|
+      case arg
+      when Integer
+        @inputs << rand(999)
+      else
+        @inputs << arg
+      end
+    end
+
+    # Action method with new arguments.
+    begin
+
+      # Validate input with controls.
+      unless @ruler.nil?
+        if @ruler.validate_inputs(@inputs)
+          @status = PASS
+        else
+          @status = FAIL
+        end
+      end
+
+      # Run reflection.
+      @output = @clone.send(@method, *@inputs)
+
+      # Validate output with controls.
+      unless @ruler.nil?
+        if @ruler.validate_output(@output)
+          @status = PASS
+        else
+          @status = FAIL
+        end
+        return
+      end
+
+    # When fail.
+    rescue StandardError => message
+      @status = FAIL
+      @message = message
+
+    # When no validation and execution fails.
+    else
+      @status = PASS
+    end
+
+  end
+
+  def result()
+    # Build reflection.
+    reflection = {
+      TIME => @time,
+      STATUS => @status,
+      INPUT => normalize_input(@inputs),
+      OUTPUT => normalize_output(@output),
+      MESSAGE => @message
+    }
+  end
+
+  ##
+  # Normalize inputs.
+  #
+  # @param args - The actual inputs.
+  # @return - A generic inputs representation.
+  ##
+  def normalize_input(args)
+    inputs = []
+    args.each do |arg|
+      input = {
+        TYPE => arg.class.to_s,
+        VALUE => normalize_value(arg)
+      }
+      if (arg.class == Array)
+        input[COUNT] = arg.count
+      end
+      inputs << input
+    end
+    inputs
+  end
+
+  ##
+  # Normalize output.
+  #
+  # @param input - The actual output.
+  # @return - A generic output representation.
+  ##
+  def normalize_output(input)
+
+    output = {
+      TYPE => input.class.to_s,
+      VALUE => normalize_value(input)
+    }
+
+    if (input.class == Array || input.class == Hash)
+      output[COUNT] = input.count
+    elsif (input.class == TrueClass || input.class == FalseClass)
+      output[TYPE] = :Boolean
+    end
+
+    return output
+
+  end
+
+  def normalize_value(value)
+
+    unless value.nil?
+      value = value.to_s.gsub(/\r?\n/, " ").to_s
+      if value.length >= 30
+        value = value[0, value.rindex(/\s/,30)].rstrip() + '...'
+      end
+    end
+
+    return value
+
+  end
+
+end

data/lib/Reflekt.rb

@@ -0,0 +1,223 @@
+################################################################################
+# REFLEKT - By Maedi Prichard.
+#
+# An Execution is created each time a method is called.
+# Many Refections are created per Execution.
+# Each Reflection executes on a ShadowStack on cloned data.
+# Then flow is returned to the original method and normal execution continues.
+#
+# Usage:
+#   class ExampleClass
+#     prepend Reflekt
+################################################################################
+
+require 'set'
+require 'erb'
+require 'rowdb'
+require 'Accessor'
+require 'Control'
+require 'Execution'
+require 'Reflection'
+require 'Renderer'
+require 'Ruler'
+require 'ShadowStack'
+
+module Reflekt
+
+  def initialize(*args)
+
+    @reflection_counts = {}
+
+    # Get instance methods.
+    # TODO: Include parent methods like "Array.include?".
+    self.class.instance_methods(false).each do |method|
+
+      # Don't process skipped methods.
+      next if self.class.reflekt_skipped?(method)
+
+      @reflection_counts[method] = 0
+
+      # When method called in flow.
+      self.define_singleton_method(method) do |*args|
+
+        # Don't reflect when limit reached.
+        unless @reflection_counts[method] >= @@reflekt.reflection_limit
+
+          # Get current execution.
+          execution = @@reflekt.stack.peek()
+
+          # When stack empty or past execution done reflecting.
+          if execution.nil? || execution.has_finished_reflecting?
+
+            # Create execution.
+            execution = Execution.new(self, @@reflekt.reflect_amount)
+            @@reflekt.stack.push(execution)
+
+          end
+
+          # Get ruler.
+          # The method's ruler will not exist the first time the db generated.
+          if @@reflekt.rules.key? execution.caller_class.to_s.to_sym
+            ruler = @@reflekt.rules[execution.caller_class.to_s.to_sym][method.to_s]
+          else
+            ruler = nil
+          end
+
+          # Reflect.
+          # The first method call in the Execution creates a Reflection.
+          # Subsequent method calls are shadow executions on cloned objects.
+          if execution.has_empty_reflections? && !execution.is_reflecting?
+            execution.is_reflecting = true
+
+            class_name = execution.caller_class.to_s
+            method_name = method.to_s
+
+            # Create control.
+            control = Control.new(execution, method, ruler)
+            execution.control = control
+
+            # Execute control.
+            control.reflect(*args)
+
+            # Save control.
+            @@reflekt.db.get("#{class_name}.#{method_name}.controls").push(control.result())
+
+            # Multiple reflections per execution.
+            execution.reflections.each_with_index do |value, index|
+
+              # Create reflection.
+              reflection = Reflection.new(execution, method, ruler)
+              execution.reflections[index] = reflection
+
+              # Execute reflection.
+              reflection.reflect(*args)
+              @reflection_counts[method] = @reflection_counts[method] + 1
+
+              # Save reflection.
+              @@reflekt.db.get("#{class_name}.#{method_name}.reflections").push(reflection.result())
+
+            end
+
+            # Save results.
+            @@reflekt.db.write()
+
+            # Render results.
+            @@reflekt.renderer.render()
+
+            execution.is_reflecting = false
+          end
+
+        end
+
+        # Continue execution / shadow execution.
+        super *args
+
+      end
+
+    end
+
+    # Continue initialization.
+    super
+
+  end
+
+  private
+
+  def self.prepended(base)
+
+    # Prepend class methods to the instance's singleton class.
+    base.singleton_class.prepend(SingletonClassMethods)
+
+    # Setup class.
+    @@reflekt = Accessor.new()
+    @@reflekt.setup ||= reflekt_setup_class
+
+  end
+
+  # Setup class.
+  def self.reflekt_setup_class()
+
+    # Receive configuration.
+    $ENV ||= {}
+    $ENV[:reflekt] ||= $ENV[:reflekt] = {}
+
+    # Set configuration.
+    @@reflekt.path = File.dirname(File.realpath(__FILE__))
+
+    # Build reflections directory.
+    if $ENV[:reflekt][:output_path]
+      @@reflekt.output_path = File.join($ENV[:reflekt][:output_path], 'reflections')
+    # Build reflections directory in current execution path.
+    else
+      @@reflekt.output_path = File.join(Dir.pwd, 'reflections')
+    end
+    # Create reflections directory.
+    unless Dir.exist? @@reflekt.output_path
+      Dir.mkdir(@@reflekt.output_path)
+    end
+
+    # Create database.
+    @@reflekt.db = Rowdb.new(@@reflekt.output_path + '/db.json')
+    @@reflekt.db.defaults({ :reflekt => { :api_version => 1 }})
+
+    # Create shadow execution stack.
+    @@reflekt.stack = ShadowStack.new()
+
+    # Define rules.
+    # TODO: Fix Rowdb.get(path) not returning data at path after Rowdb.push()?
+    @@reflekt.rules = {}
+    db = @@reflekt.db.value()
+    db.each do |class_name, class_values|
+      @@reflekt.rules[class_name] = {}
+      class_values.each do |method_name, method_values|
+        next if method_values.nil?
+        next unless method_values.class == Hash
+        if method_values.key? "controls"
+
+          ruler = Ruler.new()
+          ruler.load(method_values['controls'])
+          ruler.train()
+
+          @@reflekt.rules[class_name][method_name] = ruler
+        end
+      end
+    end
+
+    # The amount of reflections to create per method call.
+    @@reflekt.reflect_amount = 2
+
+    # Limit the amount of reflections that can be created per instance method.
+    # A method called thousands of times doesn't need that many reflections.
+    @@reflekt.reflection_limit = 10
+
+    # Create renderer.
+    @@reflekt.renderer = Renderer.new(@@reflekt.path, @@reflekt.output_path)
+
+    return true
+  end
+
+  module SingletonClassMethods
+
+    @@reflekt_skipped_methods = Set.new
+
+    ##
+    # Skip a method.
+    #
+    # @param method - A symbol representing the method name.
+    ##
+    def reflekt_skip(method)
+      @@reflekt_skipped_methods.add(method)
+    end
+
+    def reflekt_skipped?(method)
+      return true if @@reflekt_skipped_methods.include?(method)
+      false
+    end
+
+    def reflekt_limit(amount)
+      @@reflekt.reflection_limit = amount
+    end
+
+  end
+
+end