reflekt 0.9.7 → 1.0.2

data/lib/Reflekt.rb

@@ -1,12 +1,17 @@
 ################################################################################
-# REFLEKT - By Maedi Prichard.
+# Reflective testing.
 #
-# 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.
+# @author Maedi Prichard
 #
-# Usage:
+# @flow
+#   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
 #     prepend Reflekt
 ################################################################################
@@ -15,92 +20,127 @@ require 'set'
 require 'erb'
 require 'rowdb'
 require 'Accessor'
+require 'Aggregator'
+require 'Config'
 require 'Control'
 require 'Execution'
 require 'Reflection'
 require 'Renderer'
-require 'Ruler'
 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
+
+              # Execute control.
+              control.reflect(*args)
+
+              # Stop reflecting when control fails to execute.
+              if control.status == :error
+                @@reflekt.error = true
+              # Continue reflecting when control executes succesfully.
+              else
 
-          # 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
+                # Save control as reflection.
+                @@reflekt.db.get("reflections").push(control.serialize())
 
-            # Create control.
-            control = Control.new(execution, 1, @@reflekt.ruler)
-            execution.control = control
+                # Multiple reflections per execution.
+                execution.reflections.each_with_index do |value, index|
 
-            # Execute control.
-            control.reflect(*args)
+                  # Create reflection.
+                  reflection = Reflection.new(execution, index + 1, @@reflekt.aggregator)
+                  execution.reflections[index] = reflection
 
-            # Save control.
-            @@reflekt.db.get("controls").push(control.result())
+                  # Execute reflection.
+                  reflection.reflect(*args)
+                  @reflekt_counts[method] = @reflekt_counts[method] + 1
 
-            # Multiple reflections per execution.
-            execution.reflections.each_with_index do |value, index|
+                  # Save reflection.
+                  @@reflekt.db.get("reflections").push(reflection.serialize())
 
-              # Create reflection.
-              reflection = Reflection.new(execution, index + 1, @@reflekt.ruler)
-              execution.reflections[index] = reflection
+                end
 
-              # Execute reflection.
-              reflection.reflect(*args)
-              @reflekt_counts[method] = @reflekt_counts[method] + 1
+                # Save control.
+                @@reflekt.db.get("controls").push(control.serialize())
 
-              # Save reflection.
-              @@reflekt.db.get("reflections").push(reflection.result())
+                # 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.
+          super *args
 
-        # Continue execution / shadow execution.
-        super *args
+        end
 
       end
 
@@ -111,6 +151,13 @@ module Reflekt
 
   end
 
+  ##
+  # Provide Config instance to block.
+  ##
+  def self.configure
+    yield(@@reflekt.config)
+  end
+
   private
 
   def self.prepended(base)
@@ -128,18 +175,16 @@ module Reflekt
   def self.reflekt_setup_class()
 
     # Receive configuration.
-    $ENV ||= {}
-    $ENV[:reflekt] ||= $ENV[:reflekt] = {}
+    @@reflekt.config = Config.new()
 
     # Set configuration.
     @@reflekt.path = File.dirname(File.realpath(__FILE__))
 
-    # Get reflections directory path from config.
-    if $ENV[:reflekt][:output_path]
-      @@reflekt.output_path = File.join($ENV[:reflekt][:output_path], 'reflections')
-    # Get reflections directory path from current execution path.
+    # Get reflections directory path from config or current execution path.
+    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, 'reflections')
+      @@reflekt.output_path = File.join(Dir.pwd, @@reflekt.config.output_directory)
     end
 
     # Create reflections directory.
@@ -150,52 +195,35 @@ module Reflekt
     # Create database.
     @@reflekt.db = Rowdb.new(@@reflekt.output_path + '/db.js')
     @@reflekt.db.defaults({ :reflekt => { :api_version => 1 }})
+    # @TODO Fix Rowdb.get(path) not returning values at path after Rowdb.push()
+    db = @@reflekt.db.value()
 
-    # Create shadow execution stack.
+    # Create shadow stack.
     @@reflekt.stack = ShadowStack.new()
 
-    # Create rules.
-    @@reflekt.ruler = Ruler.new()
-    # TODO: Fix Rowdb.get(path) not returning values at path after Rowdb.push()?
-    values = @@reflekt.db.value()
-    values.each do |klass, class_values|
-
-      class_values.each do |method_name, method_items|
-        next if method_items.nil?
-        next unless method_items.class == Hash
-        if method_items.key? "controls"
-
-          method = method_name.to_sym
-
-          @@reflekt.ruler.load(klass, method, method_items['controls'])
-          @@reflekt.ruler.train(klass, method)
-
-        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.reflect_limit = 10
+    # Create aggregated rule sets.
+    @@reflekt.aggregator = Aggregator.new(@@reflekt.config.meta_map)
+    @@reflekt.aggregator.train(db[:controls])
 
     # Create renderer.
     @@reflekt.renderer = Renderer.new(@@reflekt.path, @@reflekt.output_path)
 
     return true
+
   end
 
   module SingletonClassMethods
 
-    @@reflekt_skipped_methods = Set.new
+    @@reflekt_skipped_methods = Set.new()
 
     ##
     # Skip a method.
     #
-    # @param method - A symbol representing the method name.
+    # @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)
       @@reflekt_skipped_methods.add(method)
@@ -206,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
 

data/lib/Renderer.rb

@@ -28,6 +28,11 @@ class Renderer
       end
     end
 
+    file = File.read(File.join(@path, "web", "gitignore.txt"))
+    File.open(File.join(@output_path, ".gitignore"), 'w+') do |f|
+      f.write file
+    end
+
   end
 
 

data/lib/Rule.rb

@@ -1,32 +1,52 @@
 ################################################################################
-# RULES
+# A pattern that metadata follows.
 #
-# Abstract class.
-# See lib/rules for rules.
+# @pattern Abstract class
+#
+# @hierachy
+#   1. Aggregator
+#   2. RuleSet
+#   3. Rule <- YOU ARE HERE
+#
+# @see lib/rules for rules.
 ################################################################################
 
-require 'set'
-
 class Rule
 
-  # Each rule intitalises itself.
-  def initialize()
-    @values = []
-  end
+  attr_reader :type
 
-  # Each rule loads up an array of values.
-  def load(value)
-    @values << value
+  ##
+  # Each rule trains on metadata to determine its boundaries.
+  #
+  # @param meta [Meta]
+  ##
+  def train(meta)
   end
 
-  # Each rule trains on values to determine its boundaries.
-  def train()
-
+  ##
+  # Each rule validates a value with its boundaries.
+  #
+  # @param value [Dynamic]
+  # @return [Boolean] Whether the value passes or fails.
+  ##
+  def test(value)
   end
 
-  # Each rule compares the values it's given with its boundaries.
-  def validate(value)
+  ##
+  # Each rule provides results.
+  #
+  # @return [Hash]
+  ##
+  def result()
+    {}
+  end
 
+  ##
+  # Each rule provides a random example that matches the rule's boundaries.
+  #
+  # @return [Dynamic] A random value.
+  ##
+  def random()
   end
 
 end

data/lib/RuleSet.rb

@@ -1,79 +1,109 @@
 ################################################################################
-# RULE POOL
+# A collection of rules that validate metadata.
 #
-# A collection of unique rules that validate an argument.
+# @patterns
+#   - Dependency Injection
+#   - Builder
+#
+# @hierachy
+#   1. Aggregator
+#   2. RuleSet <- YOU ARE HERE
+#   3. Rule
 ################################################################################
 
 require 'set'
-require 'rules/FloatRule'
-require 'rules/IntegerRule'
-require 'rules/StringRule'
+require 'MetaBuilder'
+require_relative './meta/NullMeta.rb'
 
 class RuleSet
 
-  attr_accessor :types
   attr_accessor :rules
 
-  def initialize()
+  ##
+  # @param meta_map [Hash] The rules to apply to each data type.
+  ##
+  def initialize(meta_map)
+
+    # The rules that apply to meta types.
+    @meta_map = meta_map
+
+    # The types of meta this rule set applies to.
+    # Rules are only validated on their supported meta type.
+    @meta_types = Set.new()
 
-    @types = Set.new
     @rules = {}
 
   end
 
-  def load(type, value)
+  ##
+  # Train rule set on metadata.
+  #
+  # @param meta [Hash] The metadata to train on.
+  ##
+  def train(meta)
 
-    # Track data type.
-    @types << type
+    # Track supported meta types.
+    meta_type = meta[:type]
+    @meta_types << meta_type
 
-    # Get rule for this data type.
-    rule = nil
+    # Get rule types for this meta type.
+    if @meta_map.key? meta_type
+      @meta_map[meta_type].each do |rule_type|
+
+        # Ensure rule exists.
+        if @rules[rule_type].nil?
+          @rules[rule_type] = rule_type.new()
+        end
+
+        # Train rule.
+        @rules[rule_type].train(meta)
 
-    case type
-    when "Integer"
-      unless @rules.key? IntegerRule
-        rule = IntegerRule.new()
-        @rules[IntegerRule] = rule
-      else
-        rule = @rules[IntegerRule]
-      end
-    when "String"
-      unless @rules.key? StringRule
-        rule = StringRule.new()
-        @rules[StringRule] = rule
-      else
-        rule = @rules[IntegerRule]
       end
     end
 
-    # Add value to rule.
-    unless rule.nil?
-      rule.load(value)
-    end
+  end
 
-    return self
+  ##
+  # @param value [Dynamic]
+  ##
+  def test(value)
 
-  end
+    result = true
+    meta_type = MetaBuilder.data_type_to_meta_type(value)
 
-  def train()
+    # Fail if value's meta type not testable by rule set.
+    unless @meta_types.include? meta_type
+      return false
+    end
 
     @rules.each do |klass, rule|
-      rule.train()
+      if (rule.type == meta_type)
+        unless rule.test(value)
+           result = false
+        end
+      end
     end
 
+    return result
+
   end
 
-  def validate_rule(value)
-    result = true
+  ##
+  # Get the results of the rules.
+  #
+  # @return [Array] The rules.
+  ##
+  def result()
 
-    @rules.each do |klass, rule|
+    rules = {}
 
-      unless rule.validate(value)
-        result = false
-      end
+    @rules.each do |key, rule|
+      rules[rule.class] = rule.result()
     end
 
-    return result
+    return rules
+
   end
 
+
 end