eaco 0.6.1 → 0.7.0

data/lib/eaco/cucumber/active_record/user/designators/user.rb

@@ -16,6 +16,8 @@ module Eaco
           #
           class User < Eaco::Designator
             ##
+            # This {Designator} description
+            #
             # @return [String] the {User}'s name.
             #
             def describe(*)
@@ -23,6 +25,8 @@ module Eaco
             end
 
             ##
+            # {User}s matching this designator.
+            #
             # @return [Array] this very {User} wrapped in an +Array+.
             #
             def resolve

data/lib/eaco/cucumber/world.rb

@@ -132,7 +132,7 @@ module Eaco
     class World
 
       ##
-      # Set up the World:
+      # Sets up the World:
       #
       # * Connect to ActiveRecord
       #
@@ -141,7 +141,117 @@ module Eaco
       end
 
       ##
-      # @return [Class] a model in the {ActiveRecord} namespace.
+      # Authorizes model with the given {DSL}
+      #
+      # @param name [String] the model name
+      # @param definition [String] the {DSL} code
+      # @see {#find_model}
+      #
+      # @return [void]
+      #
+      def authorize_model(name, definition)
+        model = find_model(name)
+
+        eval_dsl definition, model
+      end
+
+      ##
+      # Registers and persists an {Actor} instance with the given +name+.
+      #
+      # @param model [String] the {Actor} model name
+      # @param name [String] the {Actor} instance name
+      # @param options [Boolean] the only supported one is +admin+, and
+      #                          specifies whether this {Actor} an admin
+      #
+      # @return [Actor] the newly created {Actor} instance.
+      #
+      def register_actor(model, name, options = {})
+        actor_model = find_model(model)
+
+        actors[name] = actor_model.new.tap do |actor|
+          actor.name  = name
+          actor.admin = options.fetch(:admin, false)
+          actor.save!
+        end
+      end
+
+      ##
+      # Fetches an {Actor} instance by name.
+      #
+      # @param name [String] the actor name
+      # @return [Actor] the registered actor name
+      # @raise [RuntimeError] if the actor is not found in the registry
+      #
+      def fetch_actor(name)
+        actors.fetch(name)
+      rescue KeyError
+        # :nocov:
+        raise "Actor '#{name}' not found in registry"
+        # :nocov:
+      end
+
+      ##
+      # Registers and persists {Resource} instance with the given name.
+      #
+      # @param model [String] the {Resource} model name
+      # @param name [String] the {Resource} name
+      #
+      # @return [Resource] the newly instantiated {Resource}
+      #
+      def register_resource(model, name)
+        resource_model = find_model(model)
+
+        resource = resource_model.new.tap do |resource|
+          resource.name = name
+          resource.save!
+        end
+
+        resources[model] ||= {}
+        resources[model][name] = resource
+      end
+
+      ##
+      # Fetches a {Resource} instance by name.
+      #
+      # @param model [String] the {Resource} model name
+      # @param name [String] the {Resource} name
+      #
+      def fetch_resource(model, name)
+        resources.fetch(model).fetch(name)
+      rescue KeyError
+        # :nocov:
+        raise "Resource #{model} '#{resource}' not found in registry"
+        # :nocov:
+      end
+
+      ##
+      # All registered {Actor} instances.
+      #
+      # @return [Hash] actors keyed by name
+      #
+      def actors
+        @actors ||= {}
+      end
+
+      ##
+      # All registered {Resource} instances.
+      #
+      # @return [Hash] resources keyed by model name with +Hash+es
+      #                as values keyed by resource name.
+      #
+      def resources
+        @resources ||= {}
+      end
+
+      ##
+      # Returns a model in the {ActiveRecord} namespace.
+      #
+      # Example:
+      #
+      #   World.find_model('Document')
+      #
+      # @param model_name [String] the model name
+      # @return [Class]
       #
       def find_model(model_name)
         Eaco::Cucumber::ActiveRecord.const_get(model_name)
@@ -152,13 +262,13 @@ module Eaco
       # +$MODEL+ string with the given model name.
       #
       # @param code [String] the DSL code to eval
-      # @param model [Class] the model name to substitute
+      # @param model [Class] the model name to substitute (optional)
       #
       # @return [void]
       #
-      def eval_dsl(code, model)
+      def eval_dsl(code, model = nil)
         # Sub in place to print final code when running cucumber
-        code.sub! '$MODEL', model.name
+        code.sub! '$MODEL', model.name if model
         Eaco.eval! code, '(feature)'
       end
     end

data/lib/eaco/designator.rb

@@ -63,7 +63,7 @@ module Eaco
       # @return [Array] resolved actors, application-dependant.
       #
       def resolve(designators)
-        Array.new(designators||[]).inject([]) {|ret, d| ret.concat parse(d).resolve}
+        Array.new(designators||[]).inject(Set.new) {|ret, d| ret.merge parse(d).resolve}
       end
 
       ##
@@ -108,7 +108,9 @@ module Eaco
       # @see Actor
       #
       def harvest(actor)
-        Array.new([actor.send(@method)].flatten).map! {|value| new(value) }
+        list = actor.send(@method)
+        list = list.to_a if list.respond_to?(:to_a)
+        Array.new([list]).flatten.map! {|value| new(value) }
       end
 
       ##
@@ -167,6 +169,9 @@ module Eaco
       # in a typeahead menu, for your Enterprise authorization management
       # UI... :-)
       #
+      # @param query [String] the query to search against
+      # @return [Enumerable] application {Actor}s collection
+      #
       # @raise [NotImplementedError]
       #
       def search(query)

data/lib/eaco/dsl.rb

@@ -19,6 +19,10 @@ module Eaco
     ##
     # Entry point for the {Resource} authorization definition.
     #
+    # @param resource_class [Class] the application resource class
+    # @param options [Hash] options passed to {DSL::Resource} and
+    #                       and {DSL::ACL}.
+    #
     # @see DSL::Resource
     # @see DSL::ACL
     #
@@ -28,7 +32,11 @@ module Eaco
     end
 
     ##
-    # Entry point for the {Actor} designators definition.
+    # Entry point for an {Actor} definition.
+    #
+    # @param actor_class [Class] the application actor class
+    # @param options [Hash] currently unused
+    # @param block [Proc] the DSL code to eval
     #
     # @see DSL::Actor
     #

data/lib/eaco/dsl/acl.rb

@@ -50,7 +50,7 @@ module Eaco
       #
       def define_acl_subclass
         target_eval do
-          remove_const(:ACL) if const_defined?(:ACL)
+          remove_const(:ACL) if constants.include?(:ACL)
 
           Class.new(Eaco::ACL).tap do |acl_class|
             define_singleton_method(:acl) { acl_class }
@@ -97,7 +97,7 @@ module Eaco
           target.send(:include, adapter)
           install_authorized_collection_strategy
 
-        elsif target.respond_to?(:acl) && target.respond_to?(:acl=)
+        elsif (target.instance_methods & [:acl, :acl=]).size != 2
           raise Malformed, <<-EOF
             Don't know how to persist ACLs using <#{target}>'s ORM
             (identified as <#{orm}>). Please define an `acl' instance

data/lib/eaco/dsl/actor.rb

@@ -21,7 +21,7 @@ module Eaco
       autoload :Designators, 'eaco/dsl/actor/designators'
 
       ##
-      # Initializes an Actor class.
+      # Makes an application model a valid {Eaco::Actor}.
       #
       # @see Eaco::Actor
       #
@@ -79,7 +79,7 @@ module Eaco
 
       ##
       # Defines the boolean logic that determines whether an {Actor} is an
-      # admin. Usually you'll have an +admin+ method on your model, that you
+      # admin. Usually you'll have an +admin?+ method on your model, that you
       # can call from here. Or, feel free to just return +false+ to disable
       # this functionality.
       #
@@ -91,9 +91,12 @@ module Eaco
       #     end
       #   end
       #
+      # @param block [Proc]
+      # @return [void]
+      #
       def admin(&block)
         target_eval do
-          @admin_logic = block
+          @_admin_logic = block
         end
       end
 

data/lib/eaco/dsl/base.rb

@@ -32,6 +32,8 @@ module Eaco
       attr_reader :options
 
       ##
+      # Sets up the DSL instance target class and the options.
+      #
       # @param target [Class]
       # @param options [Hash]
       #
@@ -43,6 +45,9 @@ module Eaco
         ##
         # Evaluates the given block in the context of the target class
         #
+        # @param block [Proc]
+        # @return [void]
+        #
         def target_eval(&block)
           target.instance_eval(&block)
         end

data/lib/eaco/error.rb

@@ -5,7 +5,16 @@ module Eaco
   #
   class Error < StandardError
     # As we make use of heredoc for long error messages, squeeze subsequent
-    # spaces and remove newlines.
+    # spaces and remove newlines. If the message looks like an internal error
+    # though, newlines are preserved.
+    #
+    # Example:
+    #
+    #   raise Eaco::Error, <<-EOF
+    #     Some fancy message
+    #   end
+    #
+    # @param message [String]
     #
     def initialize(message)
       unless message =~ %r{EACO.+Error}

data/lib/eaco/rake.rb

@@ -4,6 +4,7 @@ module Eaco
   # Namespace to all rake-related functionality.
   #
   module Rake
+    autoload :Utils,       'eaco/rake/utils.rb'
     autoload :DefaultTask, 'eaco/rake/default_task.rb'
   end
 

data/lib/eaco/rake/default_task.rb

@@ -1,3 +1,5 @@
+require 'eaco/coverage'
+
 module Eaco
   module Rake
 
@@ -30,12 +32,14 @@ module Eaco
           task :default do
             run_specs
             run_cucumber
+            output_coverage
           end
 
         elsif running_in_travis?
           task :default do
             run_specs
             run_cucumber
+            report_coverage
             generate_documentation
           end
 
@@ -114,6 +118,25 @@ module Eaco
         ::Rake::Task[task].invoke
       end
 
+      ##
+      # Reports coverage data
+      #
+      # @return [void]
+      #
+      def report_coverage
+        Eaco::Coverage.report!
+      end
+
+      ##
+      # Formats code coverage results and prints a summary
+      #
+      # @return [void]
+      #
+      def output_coverage
+        summary = Eaco::Coverage.format!
+        croak summary
+      end
+
       ##
       # Fancily logs the given +msg+ to +$stderr+.
       #
@@ -142,8 +165,8 @@ module Eaco
       # @return [String]
       #
       def with_appraisal(msg)
-        if appraisal
-          msg = "%s \033[1;31m[%s]" % [msg, appraisal]
+        if gemfile
+          msg = "%s \033[1;31m[%s]" % [msg, gemfile]
         end
 
         return msg
@@ -166,14 +189,11 @@ module Eaco
       end
 
       ##
-      # @return [String] the current appraisal name, or nil
+      # @see {Rake::Utils.gemfile}
+      # @private
       #
-      def appraisal
-        return unless running_appraisals?
-
-        gemfile = ENV['BUNDLE_GEMFILE']
-
-        File.basename(gemfile, '.*') if gemfile
+      def gemfile
+        Rake::Utils.gemfile
       end
 
       ##

data/lib/eaco/rake/utils.rb

@@ -0,0 +1,38 @@
+module Eaco
+  module Rake
+
+    ##
+    # Assorted utilities.
+    #
+    module Utils
+      extend self
+
+      ##
+      # Captures the stdout emitted by the given +block+
+      #
+      # @param block [Proc]
+      # @return [String] the captured output
+      #
+      def capture_stdout(&block)
+        stdout, string = $stdout, StringIO.new
+        $stdout = string
+
+        yield
+
+        string.tap(&:rewind).read
+      ensure
+        $stdout = stdout
+      end
+
+      ##
+      # @return [String] the current gemfile name
+      #
+      def gemfile
+        gemfile = ENV['BUNDLE_GEMFILE']
+
+        File.basename(gemfile, '.*') if gemfile
+      end
+    end
+
+  end
+end

data/lib/eaco/version.rb

@@ -2,6 +2,6 @@ module Eaco
 
   # Current version
   #
-  VERSION = '0.6.1'
+  VERSION = '0.7.0'
 
 end

data/spec/eaco/acl_spec.rb

@@ -31,6 +31,24 @@ RSpec.describe Eaco::ACL do
       it { expect(subject).to be_a(described_class) }
       it { expect(subject).to include({designator => :reader}) }
     end
+
+    context 'when looking up designators' do
+      after { acl.add(:reader, :foo, 1) }
+
+      let(:acl) { described_class.new }
+
+      it { expect(Eaco::Designator).to receive(:make).with(:foo, 1) }
+    end
+
+    context 'when giving rubbish' do
+      subject { acl.add(:reader, 'rubbish') }
+
+      let(:acl) { described_class.new }
+
+      it { expect { subject }.to \
+           raise_error(Eaco::Error).
+           with_message(/Cannot infer designator from "rubbish"/) }
+    end
   end
 
   describe '#del' do
@@ -144,4 +162,20 @@ RSpec.describe Eaco::ACL do
     end
   end
 
+  describe '#inspect' do
+    let(:acl) { described_class.new('foo' => :bar) }
+
+    subject { acl.inspect }
+
+    it { expect(subject).to eq('#<Eaco::ACL: {"foo"=>:bar}>') }
+  end
+
+  describe '#pretty_inspect' do
+    let(:acl) { described_class.new('foo' => :bar) }
+
+    subject { acl.pretty_inspect }
+
+    it { expect(subject).to eq("Eaco::ACL\n{\"foo\"=>:bar}\n") }
+  end
+
 end