reflekt 0.9.8 → 1.0.3

data/lib/Execution.rb

@@ -1,3 +1,12 @@
+################################################################################
+# A shadow execution.
+#
+# @hierachy
+#   1. Execution <- YOU ARE HERE
+#   2. Reflection
+#   3. Meta
+################################################################################
+
 class Execution
 
   attr_accessor :unique_id
@@ -17,12 +26,12 @@ class Execution
   ##
   # Create Execution.
   #
-  # @param Object object - The calling object.
-  # @param Symbol method - The calling method.
-  # @param Integer number - The number of reflections to create per execution.
-  # @param ShadowStack stack - The shadow execution call stack.
+  # @param object [Object] The calling object.
+  # @param method [Symbol] The calling method.
+  # @param reflect_amount [Integer] The number of reflections to create per execution.
+  # @param stack [ShadowStack] The shadow execution call stack.
   ##
-  def initialize(caller_object, method, number, stack)
+  def initialize(caller_object, method, reflect_amount, stack)
 
     @time = Time.now.to_i
     @unique_id = @time + rand(1..99999)
@@ -42,7 +51,7 @@ class Execution
 
     # Reflections.
     @control = nil
-    @reflections = Array.new(number)
+    @reflections = Array.new(reflect_amount)
 
     # State.
     if @stack.peek() == nil

data/lib/Meta.rb

@@ -1,12 +1,24 @@
 ################################################################################
-# Meta for input and output. All meta behave the same.
+# Metadata for input and output.
 #
-# @pattern Abstract class.
+# @pattern Abstract class
 # @see lib/meta for each meta.
+#
+# @hierachy
+#   1. Execution
+#   2. Reflection
+#   3. Meta <- YOU ARE HERE
 ################################################################################
 
 class Meta
 
+  ##
+  # Each meta defines its type.
+  ##
+  def initialize()
+    @type = nil
+  end
+
   ##
   # Each meta loads values.
   #
@@ -16,12 +28,44 @@ class Meta
   end
 
   ##
-  # Each meta provides metadata.
+  # Each meta serializes metadata.
   #
   # @return [Hash]
   ##
-  def result()
+  def serialize()
     {}
   end
 
+  ##############################################################################
+  # CLASS
+  ##############################################################################
+
+  ##
+  # Deserialize metadata.
+  #
+  # @todo Deserialize should create a Meta object.
+  # @todo Require each Meta type to handle its own deserialization.
+  #
+  # @param meta [Hash] The metadata to deserialize.
+  # @param meta [Hash]
+  ##
+  def self.deserialize(meta)
+
+    # Convert nil meta into NullMeta.
+    # Meta is nil when there are no @inputs or @output on the method.
+    if meta.nil?
+      return NullMeta.new().serialize()
+    end
+
+    # Symbolize keys.
+    # TODO: Remove once "Fix Rowdb.get(path)" bug fixed.
+    meta = meta.transform_keys(&:to_sym)
+
+    # Symbolize type value.
+    meta[:type] = meta[:type].to_sym
+
+    return meta
+
+  end
+
 end

data/lib/MetaBuilder.rb

@@ -1,13 +1,13 @@
 ################################################################################
-# Create Meta.
+# Create metadata.
 #
-# @pattern Builder.
+# @pattern Builder
 # @see lib/meta for each meta.
 ################################################################################
 
 require 'Meta'
-require_relative './meta/IntegerMeta'
-require_relative './meta/StringMeta'
+# Require all meta.
+Dir[File.join(__dir__, 'meta', '*.rb')].each { |file| require file }
 
 class MetaBuilder
 
@@ -19,9 +19,16 @@ class MetaBuilder
   def self.create(value)
 
     meta = nil
+    data_type = value.class.to_s
 
-    # Creates values for matching data type.
-    case value.class.to_s
+    # Create meta type for matching data type.
+    case data_type
+    when "Array"
+      meta = ArrayMeta.new()
+    when "TrueClass", "FalseClass"
+      meta = BooleanMeta.new()
+    when "Float"
+      meta = FloatMeta.new()
     when "Integer"
       meta = IntegerMeta.new()
     when "String"
@@ -53,4 +60,25 @@ class MetaBuilder
 
   end
 
+  ##
+  # @param data_type [Type]
+  ##
+  def self.data_type_to_meta_type(value)
+
+    data_type = value.class
+
+    meta_types = {
+      Array      => :array,
+      TrueClass  => :bool,
+      FalseClass => :bool,
+      Float      => :float,
+      Integer    => :int,
+      NilClass   => :null,
+      String     => :string
+    }
+
+    return meta_types[data_type]
+
+  end
+
 end

data/lib/Reflection.rb

@@ -1,20 +1,30 @@
 ################################################################################
 # A snapshot of simulated data.
 #
+# @note
+#   A reflection's random value is within the bounds of aggregated control rule sets
+#   as well as as the arg type being inputted into the current control reflection.
+#
 # @nomenclature
-#   args/inputs/values are the same thing but at a different stage of lifecycle.
+#   args, inputs/output and meta represent different stages of a value.
 #
 # @hierachy
 #   1. Execution
-#   2. Reflection
-#   3. RuleSet
+#   2. Reflection <- YOU ARE HERE
+#   3. Meta
+#
+# @status
+#   - :pass [Symbol] The reflection passes the rules.
+#   - :fail [Symbol] The reflection fails the rules or produces a system error.
+#   - :error [Symbol] The control reflection produces a system error.
 ################################################################################
 
+require 'Clone'
 require 'MetaBuilder'
 
 class Reflection
 
-  attr_accessor :clone
+  attr_reader :status
 
   ##
   # Create a Reflection.
@@ -37,83 +47,100 @@ class Reflection
     @method = execution.method
 
     # Metadata.
-    @inputs = []
+    @inputs = nil
     @output = nil
 
     # Clone the execution's calling object.
+    # TODO: Abstract away into Clone class.
     @clone = execution.caller_object.clone
-    @clone_id = nil
 
     # Result.
     @status = :pass
     @time = Time.now.to_i
+    @message = nil
 
   end
 
   ##
   # Reflect on a method.
   #
-  # Creates a shadow execution stack.
+  # Creates a shadow execution.
   # @param *args [Dynamic] The method's arguments.
   ##
   def reflect(*args)
 
-    # Get aggregated RuleSets.
-    agg_input_rule_sets = @aggregator.get_input_rule_sets(@klass, @method)
-    agg_output_rule_set = @aggregator.get_output_rule_set(@klass, @method)
+    # Get aggregated rule sets.
+    input_rule_sets = @aggregator.get_input_rule_sets(@klass, @method)
+    output_rule_set = @aggregator.get_output_rule_set(@klass, @method)
 
-    # Create random arguments.
-    new_args = randomize(args)
+    # When arguments exist.
+    unless args.size == 0
 
-    # Create metadata for each argument.
-    @inputs = MetaBuilder.create_many(new_args)
+      # Create random arguments from aggregated rule sets.
+      unless input_rule_sets.nil?
 
-    # Action method with new arguments.
-    begin
+        # Base random arguments on the types of the current arguments.
+        if Aggregator.testable?(args, input_rule_sets)
 
-      # Validate input with aggregated control RuleSets.
-      unless agg_input_rule_sets.nil?
-        unless @aggregator.validate_inputs(new_args, agg_input_rule_sets)
+          args = randomize(args, input_rule_sets)
+
+        # TODO: Fallback to argument types from aggregated control rule sets
+        # when arg types not testable or reflect_amount above 3.
+        else
           @status = :fail
         end
+
       end
 
+      # Create metadata for each argument.
+      # TODO: Create metadata for other inputs such as properties on the instance.
+      @inputs = MetaBuilder.create_many(args)
+
+    end
+
+    # Action method with new/old arguments.
+    begin
+
       # Run reflection.
-      output = @clone.send(@method, *new_args)
+      output = @clone.send(@method, *args)
       @output = MetaBuilder.create(output)
 
-      # Validate output with aggregated control RuleSets.
-      unless agg_output_rule_set.nil?
-        unless @aggregator.validate_output(output, agg_output_rule_set)
+      # Validate output against aggregated control rule sets.
+      unless output_rule_set.nil?
+        unless @aggregator.test_output(output, output_rule_set)
           @status = :fail
         end
       end
 
-    # When fail.
+    # When a system error occurs.
     rescue StandardError => message
+
       @status = :fail
       @message = message
+
     end
 
   end
 
   ##
-  # Create random values for each argument.
+  # Create random values for each argument from control reflections.
   #
   # @param args [Dynamic] The arguments to create random values for.
+  # @param input_rule_sets [Array] Aggregated rule sets for each argument.
+  #
   # @return [Dynamic] Random arguments.
   ##
-  def randomize(args)
+  def randomize(args, input_rule_sets)
 
     random_args = []
 
-    args.each do |arg|
-      case arg
-      when Integer
-        random_args << rand(999)
-      else
-        random_args << arg
-      end
+    args.each_with_index do |arg, arg_num|
+
+      rule_type = Aggregator.value_to_rule_type(arg)
+      agg_rule = input_rule_sets[arg_num].rules[rule_type]
+
+      random_args << agg_rule.random()
+
     end
 
     return random_args
@@ -125,7 +152,7 @@ class Reflection
   #
   # @return [Hash] Reflection metadata.
   ##
-  def result()
+  def serialize()
 
     # The ID of the first execution in the ShadowStack.
     base_id = nil
@@ -144,11 +171,19 @@ class Reflection
       :method => @method,
       :status => @status,
       :message => @message,
-      :inputs => [],
-      :output => @output,
+      :inputs => nil,
+      :output => nil,
     }
-    @inputs.each do |meta|
-      reflection[:inputs] << meta.result()
+
+    unless @inputs.nil?
+      reflection[:inputs] = []
+      @inputs.each do |meta|
+        reflection[:inputs] << meta.serialize()
+      end
+    end
+
+    unless @output.nil?
+      reflection[:output] = @output.serialize()
     end
 
     return reflection

data/lib/Reflekt.rb

@@ -1,14 +1,15 @@
 ################################################################################
 # Reflective testing.
 #
-# @author
-#   Maedi Prichard
+# @author Maedi Prichard
 #
 # @flow
-#   1. An Execution is created on method call.
-#   2. Many Refections are created per Execution.
-#   3. Each Reflection executes on cloned data.
-#   4. Flow is returned to the original method.
+#   1. Reflekt is prepended to a class and setup.
+#   2. When a class insantiates so does Reflekt.
+#   3. An Execution is created on method call.
+#   4. Many Refections are created per Execution.
+#   5. Each Reflection executes on cloned data.
+#   6. Flow is returned to the original method.
 #
 # @usage
 #   class ExampleClass
@@ -20,91 +21,126 @@ require 'erb'
 require 'rowdb'
 require 'Accessor'
 require 'Aggregator'
+require 'Config'
 require 'Control'
 require 'Execution'
 require 'Reflection'
 require 'Renderer'
 require 'ShadowStack'
+# Require all rules.
+Dir[File.join(__dir__, 'rules', '*.rb')].each { |file| require file }
 
 module Reflekt
 
   def initialize(*args)
 
+    # TODO: Store counts on @@reflekt and key by instance ID.
     @reflekt_counts = {}
 
-    # Get instance methods.
-    # TODO: Include parent methods like "Array.include?".
-    self.class.instance_methods(false).each do |method|
+    # Get child and parent instance methods.
+    parent_instance_methods = self.class.superclass.instance_methods(false)
+    child_instance_methods = self.class.instance_methods(false)
+    instance_methods = parent_instance_methods + child_instance_methods
 
-      # Don't process skipped methods.
-      next if self.class.reflekt_skipped?(method)
+    # TODO: Include core methods like "Array.include?".
+    instance_methods.each do |method|
 
       @reflekt_counts[method] = 0
 
       # When method called in flow.
       self.define_singleton_method(method) do |*args|
 
-        # Don't reflect when limit reached.
-        unless @reflekt_counts[method] >= @@reflekt.reflect_limit
+        # When Reflekt enabled and control reflection has executed without error.
+        if @@reflekt.config.enabled && !@@reflekt.error
 
           # Get current execution.
           execution = @@reflekt.stack.peek()
 
-          # When stack empty or past execution done reflecting.
-          if execution.nil? || execution.has_finished_reflecting?
+          # Don't reflect when reflect limit reached or method skipped.
+          unless (@reflekt_counts[method] >= @@reflekt.config.reflect_limit) || self.class.reflekt_skipped?(method)
 
-            # Create execution.
-            execution = Execution.new(self, method, @@reflekt.reflect_amount, @@reflekt.stack)
+            # When stack empty or past execution done reflecting.
+            if execution.nil? || execution.has_finished_reflecting?
 
-            @@reflekt.stack.push(execution)
+              # Create execution.
+              execution = Execution.new(self, method, @@reflekt.config.reflect_amount, @@reflekt.stack)
 
-          end
+              @@reflekt.stack.push(execution)
+
+            end
+
+            ##
+            # Reflect the execution.
+            #
+            # The first method call in the execution creates a reflection.
+            # Then method calls are shadow executions which return to the reflection.
+            ##
+            if execution.has_empty_reflections? && !execution.is_reflecting?
+              execution.is_reflecting = true
+
+              # Create control.
+              control = Control.new(execution, 0, @@reflekt.aggregator)
+              execution.control = control
 
-          # 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
+              # Execute control.
+              control.reflect(*args)
 
-            # Create control.
-            control = Control.new(execution, 1, @@reflekt.aggregator)
-            execution.control = control
+              # Stop reflecting when control fails to execute.
+              if control.status == :error
+                @@reflekt.error = true
+              # Continue reflecting when control executes succesfully.
+              else
 
-            # Execute control.
-            control.reflect(*args)
+                # Save control as reflection.
+                @@reflekt.db.get("reflections").push(control.serialize())
 
-            # Save control.
-            @@reflekt.db.get("controls").push(control.result())
+                # Multiple reflections per execution.
+                execution.reflections.each_with_index do |value, index|
 
-            # Multiple reflections per execution.
-            execution.reflections.each_with_index do |value, index|
+                  # Create reflection.
+                  reflection = Reflection.new(execution, index + 1, @@reflekt.aggregator)
+                  execution.reflections[index] = reflection
 
-              # Create reflection.
-              reflection = Reflection.new(execution, index + 1, @@reflekt.aggregator)
-              execution.reflections[index] = reflection
+                  # Execute reflection.
+                  reflection.reflect(*args)
+                  @reflekt_counts[method] = @reflekt_counts[method] + 1
 
-              # Execute reflection.
-              reflection.reflect(*args)
-              @reflekt_counts[method] = @reflekt_counts[method] + 1
+                  # Save reflection.
+                  @@reflekt.db.get("reflections").push(reflection.serialize())
 
-              # Save reflection.
-              @@reflekt.db.get("reflections").push(reflection.result())
+                end
 
+                # Save control.
+                @@reflekt.db.get("controls").push(control.serialize())
+
+                # Save results.
+                @@reflekt.db.write()
+
+                # Render results.
+                @@reflekt.renderer.render()
+
+              end
+
+              execution.is_reflecting = false
             end
 
-            # Save results.
-            @@reflekt.db.write()
+          end
+
+          # Don't execute skipped methods when reflecting.
+          unless execution.is_reflecting? && self.class.reflekt_skipped?(method)
 
-            # Render results.
-            @@reflekt.renderer.render()
+            # Continue execution / shadow execution.
+            super *args
 
-            execution.is_reflecting = false
           end
 
-        end
+        # When Reflekt disabled or control reflection failed.
+        else
 
-        # Continue execution / shadow execution.
-        super *args
+          # Continue execution.
+          super *args
+
+        end
 
       end
 
@@ -115,6 +151,13 @@ module Reflekt
 
   end
 
+  ##
+  # Provide Config instance to block.
+  ##
+  def self.configure
+    yield(@@reflekt.config)
+  end
+
   private
 
   def self.prepended(base)
@@ -132,18 +175,16 @@ module Reflekt
   def self.reflekt_setup_class()
 
     # Receive configuration.
-    $ENV ||= {}
-    $ENV[:reflekt] ||= $ENV[:reflekt] = {}
-    $ENV[:reflekt][:output_directory] = "reflections"
+    @@reflekt.config = Config.new()
 
     # Set configuration.
     @@reflekt.path = File.dirname(File.realpath(__FILE__))
 
     # Get reflections directory path from config or current execution path.
-    if $ENV[:reflekt][:output_path]
-      @@reflekt.output_path = File.join($ENV[:reflekt][:output_path], $ENV[:reflekt][:output_directory])
+    if @@reflekt.config.output_path
+      @@reflekt.output_path = File.join(@@reflekt.config.output_path, @@reflekt.config.output_directory)
     else
-      @@reflekt.output_path = File.join(Dir.pwd, $ENV[:reflekt][:output_directory])
+      @@reflekt.output_path = File.join(Dir.pwd, @@reflekt.config.output_directory)
     end
 
     # Create reflections directory.
@@ -161,16 +202,9 @@ module Reflekt
     @@reflekt.stack = ShadowStack.new()
 
     # Create aggregated rule sets.
-    @@reflekt.aggregator = Aggregator.new()
+    @@reflekt.aggregator = Aggregator.new(@@reflekt.config.meta_map)
     @@reflekt.aggregator.train(db[:controls])
 
-    # 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.reflect_limit = 10
-
     # Create renderer.
     @@reflekt.renderer = Renderer.new(@@reflekt.path, @@reflekt.output_path)
 
@@ -185,6 +219,10 @@ module Reflekt
     ##
     # Skip a method.
     #
+    # @note
+    #  Class variables cascade to child classes.
+    #  So a reflekt_skip on the parent class will persist to the child class.
+    #
     # @param method [Symbol] The method name.
     ##
     def reflekt_skip(method)
@@ -196,9 +234,9 @@ module Reflekt
       false
     end
 
-    def reflekt_limit(amount)
-      @@reflekt.reflect_limit = amount
-    end
+    #def reflekt_limit(amount)
+    #  @@reflekt.reflect_limit = amount
+    #end
 
   end