kan 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 4b05a0ee35f96b6d7cf1860821bbb9377ce6865d
-  data.tar.gz: 2c95160455b028aeddc5888a39659f61a2fef75e
+SHA256:
+  metadata.gz: 7905462f6cf7046f2348d0fd4a72eeaa8388d65ca37e82d3b1817adcb8b0b5c5
+  data.tar.gz: 1e55a1e1b765f290110270a3ecf49fc9335979701030b3273f2ac155fb6918cc
 SHA512:
-  metadata.gz: e2d8dc36dfdfebf3da5f453824cc94b46f478346963d10d1d92c23873045cb2efb94debd260d5192e3233931236d09e80ede00b60e75e61b88b189e34fa55dc1
-  data.tar.gz: bc672426e146ad132e7339dd780c171e8da22ce350b70d9fc54a6bd1c1f9a5505faa64f5009c01d20036fab86ab37f19396b034314c2f4bb92d7f98aa76702c9
+  metadata.gz: 0e431fe2a8833613fcfdcf5735c33a42e8627fa7ec57bb22a1560a5a4cfeae5b048c44b3adec766fff2c8db09ebf599654d2d84179301479b3ae8d7a11dc41d9
+  data.tar.gz: e2e3396a2f552d3c326a09cd707c1fa9c40cd92ce7e171e718a1f61f7f810fe804c9f25061673d2d0de8f5b32003e2920e58769972019ba5e287e2adba18df96

data/.gitignore

@@ -6,3 +6,4 @@
 /pkg/
 /spec/reports/
 /tmp/
+.rubocop-https-*

data/.rubocop.yml

@@ -0,0 +1,15 @@
+# Please keep AllCops, Bundler, Style, Metrics groups and then order cops
+# alphabetically
+inherit_from:
+  - https://raw.githubusercontent.com/hanami/devtools/master/.rubocop.yml
+AllCops:
+  Exclude:
+    - "examples/**/*"
+    - "vendor/**/*"
+    - "spec/support/**/*"
+    - "**/*.gemspec"
+Style/IndentHeredoc:
+  Enabled: true
+Style/MixinGrouping:
+  Exclude:
+    - "spec/support/**/*"

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 ## HEAD
 
+* Add rubocop to the project (@davydovanton)
+* Raise error if application take invalid scope (@davydovanton) #31
+* Raise error if user try to register `roles` ability (@davydovanton) #30
+* Allow to detect roles for abilities object and scope (@davydovanton) #28
+* New documentation page (@davydovanton) #21
+
+## v0.3
+
+* Allow to use callable objects as a role objects (@davydovanton) #20
+* Allow to use classes as a role objects (@davydovanton) #18
+* Add `#permit` matcher for rspec specs (@berniechiu) #15
+
 ## v0.2
 
 * Add logger support (@valikos) #7

data/Gemfile

@@ -1,6 +1,8 @@
 source "https://rubygems.org"
 
-git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
 
 # Specify your gem's dependencies in kan.gemspec
 gemspec
+
+gem 'rubocop', '0.50.0', require: false

data/Gemfile.lock

@@ -1,11 +1,12 @@
 PATH
   remote: .
   specs:
-    kan (0.2.0)
+    kan (0.4.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
+    ast (2.4.0)
     concurrent-ruby (1.0.5)
     diff-lcs (1.3)
     dry-auto_inject (0.4.5)
@@ -15,6 +16,12 @@ GEM
     dry-container (0.6.0)
       concurrent-ruby (~> 1.0)
       dry-configurable (~> 0.1, >= 0.1.3)
+    parallel (1.12.1)
+    parser (2.5.1.0)
+      ast (~> 2.4.0)
+    powerpack (0.1.2)
+    rainbow (2.2.2)
+      rake
     rake (10.5.0)
     rspec (3.7.0)
       rspec-core (~> 3.7.0)
@@ -29,6 +36,15 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.7.0)
     rspec-support (3.7.0)
+    rubocop (0.50.0)
+      parallel (~> 1.10)
+      parser (>= 2.3.3.1, < 3.0)
+      powerpack (~> 0.1)
+      rainbow (>= 2.2.2, < 3.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (~> 1.0, >= 1.0.1)
+    ruby-progressbar (1.9.0)
+    unicode-display_width (1.4.0)
 
 PLATFORMS
   ruby
@@ -39,6 +55,7 @@ DEPENDENCIES
   kan!
   rake (~> 10.0)
   rspec (~> 3.7)
+  rubocop (= 0.50.0)
 
 BUNDLED WITH
    1.16.1

data/README.md

@@ -7,12 +7,6 @@ Simple functional authorization library for ruby. Inspired by [transproc](https:
 
 * [Installation](#installation)
 * [Usage](#usage)
-  * [Register abilities](#register-abilities)
-  * [Check abilities](#check-abilities)
-    * [Default ability block](#default-ability-block)
-    * [List of abilities](#list-of-abilities)
-  * [Roles](#roles)
-  * [Dry-auto\_inject](#dry-auto_inject)
 * [Contributing](#contributing)
 * [License](#license)
 * [Code of Conduct](#code-of-conduct)
@@ -35,15 +29,25 @@ Or install it yourself as:
 
 ## Usage
 
+See [User Documentation page](https://blog.davydovanton.com/kan/)
+
+* [Base Usage](https://blog.davydovanton.com/kan/)
+* [Roles](https://blog.davydovanton.com/kan/roles)
+* [Testing](https://blog.davydovanton.com/kan/testing)
+* [Dry integration](https://blog.davydovanton.com/kan/working_with_dry)
+* [F.A.Q.]()https://blog.davydovanton.com/kan/faq
+
+## Basic Usage
+
 ### Register abilities
 
 ```ruby
 class Post::Abilities
   include Kan::Abilities
 
-  register 'read' { |_, _| true }
-  register 'edit' { |user, post| user.id == post.user_id }
-  register 'delete' { |_, _| false }
+  register('read') { |_, _| true }
+  register('edit') { |user, post| user.id == post.user_id }
+  register('delete') { |_, _| false }
 end
 ```
 
@@ -53,16 +57,16 @@ Also, you can register more than one ability in one place and use string or symb
 class Post::AdminAbilities
   include Kan::Abilities
 
-  register :read, :edit, :delete { |user, _| user.admin? }
+  register(:read, :edit, :delete) { |user, _| user.admin? }
 end
 
 class Comments::Abilities
   include Kan::Abilities
 
-  register 'read' { |_, _| true }
-  register 'edit' { |user, _| user.admin? }
+  register('read') { |_, _| true }
+  register('edit') { |user, _| user.admin? }
 
-  register :delete do |user, comment|
+  register(:delete) do |user, comment|
     user.id == comment.user_id && comment.created_at < Time.now + TEN_MINUTES
   end
 end
@@ -116,123 +120,15 @@ global_abilities['post.edit'].call(owner_user, post)   # => true
 global_abilities['post.edit'].call(admin_user, post)   # => true
 ```
 
-### Roles
-Kan provide simple role system. For this you need to define role block in each abilities classes:
-```ruby
-module Post
-  class AnonymousAbilities
-    include Kan::Abilities
-
-    role :anonymous do |user, _|
-      user.id.nil?
-    end
-
-    register(:read, :edit, :delete) { false }
-  end
-
-  class BaseAbilities
-    include Kan::Abilities
-
-    role :all do |_, _|
-      true
-    end
-
-    register(:read) { |_, _| true }
-    register(:edit, :delete) { |user, post| false }
-  end
-
-
-  class AuthorAbilities
-    include Kan::Abilities
-
-    role :author do |user, post|
-      user.id == post.author_id
-    end
-
-    register(:read, :edit) { |_, _| true }
-    register(:delete) { |_, _| false }
-  end
-
-  class AdminAbilities
-    include Kan::Abilities
-
-    role :admin do |user, _|
-      user.admin?
-    end
-
-    register :read, :edit, :delete { |_, _| true }
-  end
-end
-```
-
-After that initialize Kan application object and call it with payload:
-```ruby
-abilities = Kan::Application.new(
-  post: [Post::AnonymousAbilities.new, Post::BaseAbilities.new, Post::AuthorAbilities.new, Post::AdminAbilities.new],
-  comment: Comments::Abilities.new
-)
-
-abilities['post.read'].call(anonymous, post) # => false
-abilities['post.read'].call(regular, post)   # => true
-abilities['post.read'].call(author, post)    # => true
-abilities['post.read'].call(admin, post)     # => true
-
-abilities['post.edit'].call(anonymous, post) # => false
-abilities['post.edit'].call(regular, post)   # => false
-abilities['post.edit'].call(author, post)    # => true
-abilities['post.edit'].call(admin, post)     # => true
-
-abilities['post.delete'].call(anonymous, post) # => false
-abilities['post.delete'].call(regular, post)   # => false
-abilities['post.delete'].call(author, post)    # => false
-abilities['post.delete'].call(admin, post)     # => true
-```
-
-### Logger support
-By default kan support default ruby logger (`Logger.new` class). For setup custom logger you can use `logger` option for each abilities instances:
-```ruby
-abilities = Kan::Application.new(
-  comment: Comments::Abilities.new(logger: MyCustomLogger.new)
-)
-```
-
-And call it from ability block:
-```ruby
-class AnonymousAbilities
-  include Kan::Abilities
-
-  register(:read, :edit, :delete) do
-    logger.info 'Anonymous ability checked'
-    false
-  end
-end
-```
-
-### Dry-auto\_inject
-```ruby
-AbilitiesImport = Dry::AutoInject(Kan::Application.new({}))
-
-# Operation
-
-class UpdateOperation
-  include AbilitiesImport[ability_checker: 'post.edit']
-
-  def call(user, params)
-    return Left(:permission_denied) unless ability_checker.call(user)
-    # ...
-  end
-end
-
-# Specs
-
-UpdateOperation.new(ability_checker: ->(*) { true })
-UpdateOperation.new(ability_checker: ->(*) { false })
-```
-
 ## Contributing
 
+### Code and features
+
 Bug reports and pull requests are welcome on GitHub at https://github.com/davydovanton/kan. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
 
+### Docs
+Just send PR with changes in `docs/` folder.
+
 ### How to instal the project
 Just clone repository and call:
 

data/Rakefile

@@ -7,6 +7,6 @@ begin
   RSpec::Core::RakeTask.new(:spec)
 
   task default: :spec
-rescue LoadError
+rescue LoadError # rubocop:disable Lint/HandleExceptions
   # no rspec available
 end

data/docs/_config.yml

@@ -0,0 +1,3 @@
+theme: jekyll-theme-primer
+title: Kan
+description: User documentation

data/docs/_layouts/default.html

@@ -0,0 +1,38 @@
+<!DOCTYPE html>
+<html lang="{{ site.lang | default: "en-US" }}">
+  <head>
+    <meta charset="UTF-8">
+    <meta http-equiv="X-UA-Compatible" content="IE=edge">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+
+    {% seo %}
+    <link rel="stylesheet" href="{{ "/assets/css/style.css?v=" | append: site.github.build_revision | relative_url }}">
+  </head>
+  <body>
+    <div class="container-lg px-3 my-5 markdown-body">
+      {% if site.title and site.title != page.title %}
+      <h1><a href="{{ "/" | absolute_url }}">{{ site.title }}</a></h1>
+      <p><a href="http://github.com/davydovanton/kan">GitHub</a></p>
+      {% endif %}
+
+      <p>Simple functional authorization library and role managment for ruby. Inspired by <a href="https://github.com/solnic/transproc">transproc</a> and <a href="http://dry-rb.org">dry project</a></p>
+
+      <ul>
+        <li><a href="{{ "/" | absolute_url }}">Base Usage</a></li>
+        <li><a href="{{ "/roles" | absolute_url }}">Roles</a></li>
+        <li><a href="{{ "/testing" | absolute_url }}">Testing</a></li>
+        <li><a href="{{ "/working_with_dry" | absolute_url }}">Dry integration</a></li>
+        <li><a href="{{ "/faq" | absolute_url }}">F.A.Q.</a></li>
+      </ul>
+
+      {{ content }}
+
+      {% if site.github.private != true and site.github.license %}
+      <div class="footer border-top border-gray-light mt-5 pt-3 text-right text-gray">
+        This site is open source. {% github_edit_link "Improve this page" %}.
+      </div>
+      {% endif %}
+
+    </div>
+  </body>
+</html>

data/docs/faq.md

@@ -0,0 +1,24 @@
+## F.A.Q.
+
+> In the example "Also, you can register more than one ability in one place and use string or symbol keys:", I don't understand how these ablities are triggered -- do PostAbilities and AdminAbilities somehow both apply at once? Can you add to this example to show how you'd call the auth check, and what would be checked?
+
+Kan will call each ability object from your register list. If all objects return `false` `abilities[name].call(payload)` will return `false` too. I.e.:
+
+```ruby
+abilities = Kan::Application.new(
+  post: [Post::Abilities.new, Post::AdminAbilities.new],
+  comment: Comments::Abilities.new
+)
+
+# [Post::Abilities.new -> false, Post::AdminAbilities.new -> false] -> false
+abilities['post.edit'].call(current_user, post)
+# => false
+
+# [Post::Abilities.new -> true, Post::AdminAbilities.new -> false] -> true
+global_abilities['post.edit'].call(owner_user, post)
+# => true
+
+# [Post::Abilities.new -> false, Post::AdminAbilities.new -> true] -> true
+abilities['post.edit'].call(admin_user, post)
+# => true
+```

data/docs/index.md

@@ -0,0 +1,81 @@
+## Basic Usage
+### Register abilities
+
+```ruby
+class Post::Abilities
+  include Kan::Abilities
+
+  register('read') { |_, _| true }
+  register('edit') { |user, post| user.id == post.user_id }
+  register('delete') { |_, _| false }
+end
+```
+
+Also, you can register more than one ability in one place and use string or symbol keys:
+
+```ruby
+class Post::AdminAbilities
+  include Kan::Abilities
+
+  register(:read, :edit, :delete) { |user, _| user.admin? }
+end
+
+class Comments::Abilities
+  include Kan::Abilities
+
+  register('read') { |_, _| true }
+  register('edit') { |user, _| user.admin? }
+
+  register(:delete) do |user, comment|
+    user.id == comment.user_id && comment.created_at < Time.now + TEN_MINUTES
+  end
+end
+```
+
+### Check abilities
+
+```ruby
+abilities = Kan::Application.new(
+  post: Post::Abilities.new,
+  comment: Comments::Abilities.new
+)
+
+abilities['post.read'].call(current_user, post) # => true
+abilities['post.delete'].call(current_user, post) # => false
+abilities['comment.delete'].call(current_user, post) # => false
+```
+
+#### Default ability block
+
+By default Kan use `proc { true }` as a default ability block:
+
+```ruby
+abilities['comment.invalid'].call(current_user, post) # => true
+```
+
+But you can rewrite it
+
+```ruby
+admin_abilities = Kan::Application.new(
+  post: Post::AdminAbilities.new(default_ability_block: proc { false }),
+  comment: Comments::Abilities.new,
+)
+
+admin_abilities['post.delete'].call(current_user, post)  # => false
+admin_abilities['post.delete'].call(admin_user, post)    # => true
+admin_abilities['post.invalid'].call(current_user, post) # => false
+```
+
+#### List of abilities
+You can provide array of abilities for each scope and Kan will return `true` if at least one ability return `true`:
+
+```ruby
+global_abilities = Kan::Application.new(
+  post: [Post::Abilities.new, Post::AdminAbilities.new],
+  comment: Comments::Abilities.new
+)
+
+global_abilities['post.edit'].call(current_user, post) # => false
+global_abilities['post.edit'].call(owner_user, post)   # => true
+global_abilities['post.edit'].call(admin_user, post)   # => true
+```

data/docs/roles.md

@@ -0,0 +1,178 @@
+## Roles
+Kan provide simple role system. It will detect all abilities object where role is true. For this you need to define role block in each abilities classes:
+
+```ruby
+module Post
+  class AnonymousAbilities
+    include Kan::Abilities
+
+    role(:anonymous) do |user, _|
+      user.id.nil?
+    end
+
+    register(:read, :edit, :delete) { false }
+  end
+
+  class BaseAbilities
+    include Kan::Abilities
+
+    role(:all) do |_, _|
+      true
+    end
+
+    register(:read) { |_, _| true }
+    register(:edit, :delete) { |user, post| false }
+  end
+
+
+  class AuthorAbilities
+    include Kan::Abilities
+
+    role(:author) do |user, post|
+      user.id == post.author_id
+    end
+
+    register(:read, :edit) { |_, _| true }
+    register(:delete) { |_, _| false }
+  end
+
+  class AdminAbilities
+    include Kan::Abilities
+
+    role(:admin) do |user, _|
+      user.admin?
+    end
+
+    register(:read, :edit, :delete) { |_, _| true }
+  end
+end
+```
+
+After that initialize Kan application object and call it with payload:
+
+```ruby
+abilities = Kan::Application.new(
+  post: [Post::AnonymousAbilities.new, Post::BaseAbilities.new, Post::AuthorAbilities.new, Post::AdminAbilities.new],
+  comment: Comments::Abilities.new
+)
+
+abilities['post.read'].call(anonymous, post) # => role: true (anonymous), result: false
+abilities['post.read'].call(regular, post)   # => role: true (base), result: true
+abilities['post.read'].call(author, post)    # => role: true (author), result: true
+abilities['post.read'].call(admin, post)     # => role: true (admin), result: true
+
+abilities['post.edit'].call(anonymous, post) # => false
+abilities['post.edit'].call(regular, post)   # => false
+abilities['post.edit'].call(author, post)    # => true
+abilities['post.edit'].call(admin, post)     # => true
+
+abilities['post.delete'].call(anonymous, post) # => false
+abilities['post.delete'].call(regular, post)   # => false
+abilities['post.delete'].call(author, post)    # => false
+abilities['post.delete'].call(admin, post)     # => true
+```
+
+### Class objects as role
+
+Kan allow to use classes as roles for incapulate and easily testing your roles.
+
+```ruby
+module Post
+  module Roles
+    class Admin
+      def call(user, _)
+        user.admin?
+      end
+    end
+
+    class Anonymous
+      def call(user, _)
+        user.id.nil?
+      end
+    end
+  end
+
+  class AnonymousAbilities
+    include Kan::Abilities
+
+    role :anonymous, Anonymous
+
+    register(:read, :edit, :delete) { false }
+  end
+
+  class AdminAbilities
+    include Kan::Abilities
+
+    role :admin, Roles::Admin
+
+    register(:read, :edit, :delete) { |_, _| true }
+  end
+end
+```
+
+#### Callable objects as role
+
+Kan allow to use "callable" (objects with `#call` method) as a role object. For this just put it into ability class:
+
+```ruby
+module Post
+  module Roles
+    class Admin
+      def call(user, _)
+        user.admin?
+      end
+    end
+
+    class Anonymous
+      def call(user, _)
+        user.id.nil?
+      end
+    end
+  end
+
+  class AnonymousAbilities
+    include Kan::Abilities
+
+    role :anonymous, Roles::Anonymous.new
+
+    register(:read, :edit, :delete) { false }
+  end
+
+  class AdminAbilities
+    include Kan::Abilities
+
+    role :admin, Container['post.roles.admin'] # or use dry-container
+
+    register(:read, :edit, :delete) { |_, _| true }
+  end
+end
+```
+
+### Detect Roles
+
+Kan allow to detect all roles for specific payload. For this use `roles` calls in scope:
+
+```ruby
+module Post
+  class AnonymousAbilities
+    include Kan::Abilities
+
+    role :anonymous, Roles::Anonymous.new
+    register(:read, :edit, :delete) { false }
+  end
+
+  class AdminAbilities
+    include Kan::Abilities
+
+    role :admin, Roles::Admin.new
+    register(:read, :edit, :delete) { |_, _| true }
+  end
+end
+
+abilities = Kan::Application.new(
+  post: [AnonymousAbilities.new, AdminAbilities.new]
+)
+
+abilities['post.roles'].call(anonymous_user, payload) # => [:anonymous]
+abilities['post.roles'].call(admin_user, payload)     # => [:anonymous, :admin]
+```

data/docs/testing.md

@@ -0,0 +1,127 @@
+## Testing
+
+For expample we have a simple kan class:
+
+```ruby
+
+module Comments
+  module Roles
+    class Admin
+      def call(user, _)
+        user.admin?
+      end
+    end
+  end
+
+  class Abilities
+    include Kan::Abilities
+
+    role :admin, Roles::Admin.new
+
+    register('read') { |user, _| user&.id }
+
+    register('edit') do |user, comment|
+      user.id == comment.id || user.admin?
+    end
+  end
+end
+```
+
+### Ability
+
+For testing specific ability use `#ability` Abilities method:
+
+```ruby
+RSpec.describe Comments::Abilities do
+  let(:abilities) { described_class.new }
+
+  subject { ability.call(account, nil) }
+
+  describe 'read ability' do
+    let(:ability) { abilities.ability(:read) } # it will return proc object
+
+    context 'when user login' do
+      let(:user) { User.new(id: 1) }
+
+      it { expect(subject).to eq true }
+    end
+
+    context 'when user anonymous' do
+      let(:user) { User.new(id: 1) }
+
+      it { expect(subject).to eq false }
+    end
+  end
+end
+```
+
+Or testing specific ability using custom matchers:
+
+```ruby
+RSpec.describe Comments::Abilities, type: :ability do
+  subject do
+    Kan::Application.new(
+      user:    Users::Abilities.new,
+      comment: Comments::Abilities.new
+    )
+  end
+
+  describe 'read ability' do
+    context 'when user login' do
+      let(:user) { User.new(id: 1) }
+      it { is_expected.to permit('comment.read', user) }
+    end
+
+    context 'when user anonymous' do
+      let(:user) { User.new(id: 1) }
+      it { is_expected.not_to permit('comment.read', user) }
+    end
+  end
+end
+```
+
+### Role
+
+For testing role you can use two ways. The first - test role object:
+
+```ruby
+RSpec.describe Comments::Abilities, type: :ability do
+  let(:role) { Comments::Role::Admin.new }
+
+  subject { role.call(user) }
+
+  context 'when user admin' do
+    let(:user) { User.new(admin: true) }
+
+    it { expect(subject).to be_true }
+  end
+
+  context 'when user anonymous' do
+    let(:user) { User.new(admin: false) }
+
+    it { expect(subject).to be_false }
+  end
+end
+```
+
+Or use `#role_block` class method:
+
+```ruby
+RSpec.describe Comments::Abilities, type: :ability do
+  let(:role) { Comments::Abilities.role_block }
+
+  subject { role.call(user) }
+
+  context 'when user admin' do
+    let(:user) { User.new(admin: true) }
+
+    it { expect(subject).to be_true }
+  end
+
+  context 'when user anonymous' do
+    let(:user) { User.new(admin: false) }
+
+    it { expect(subject).to be_false }
+  end
+end
+```

data/docs/working_with_dry.md

@@ -0,0 +1,21 @@
+## Dry-auto\_inject
+
+```ruby
+AbilitiesImport = Dry::AutoInject(Kan::Application.new({}))
+
+# Operation
+
+class UpdateOperation
+  include AbilitiesImport[ability_checker: 'post.edit']
+
+  def call(user, params)
+    return Left(:permission_denied) unless ability_checker.call(user)
+    # ...
+  end
+end
+
+# Specs
+
+UpdateOperation.new(ability_checker: ->(*) { true })
+UpdateOperation.new(ability_checker: ->(*) { false })
+```

data/lib/kan/abilities.rb

@@ -6,18 +6,24 @@ module Kan
       base.extend(ClassMethods)
     end
 
+    class InvalidRoleObjectError < StandardError; end
+    class InvalidAbilityNameError < StandardError; end
+
     module ClassMethods
       DEFAULT_ROLE_NAME = :base
       DEFAULT_ROLE_BLOCK = proc { true }
 
       def register(*abilities, &block)
+        abilities.map!(&:to_sym)
+        raise InvalidAbilityNameError if abilities.include?(:roles)
+
         @ability_list ||= {}
-        abilities.each { |ability| @ability_list[ability.to_sym] = block }
+        abilities.each { |ability| @ability_list[ability] = block }
       end
 
-      def role(role_name, &block)
+      def role(role_name, object = nil, &block)
         @role_name = role_name
-        @role_block = block
+        @role_block = object ? make_callable(object) : block
       end
 
       def role_name
@@ -35,6 +41,16 @@ module Kan
       def ability_list
         @ability_list || {}
       end
+
+      private
+
+      def make_callable(object)
+        callable_object = object.is_a?(Class) ? object.new : object
+
+        return callable_object if callable_object.respond_to? :call
+
+        raise InvalidRoleObjectError.new "role object #{object} does not support #call method"
+      end
     end
 
     DEFAULT_ABILITY_BLOCK = proc { true }
@@ -48,7 +64,7 @@ module Kan
 
     def ability(name)
       rule = self.class.ability_list[name.to_sym] || @options[:default_ability_block] || DEFAULT_ABILITY_BLOCK
-      lambda { |*args| instance_exec(args, &rule) }
+      ->(*args) { instance_exec(args, &rule) }
     end
   end
 end

data/lib/kan/abilities_list.rb

@@ -1,14 +1,28 @@
 module Kan
   class AbilitiesList
+    ROLES_DETECT = 'roles'.freeze
+
     def initialize(name, list)
       @name = name
       @list = list
     end
 
     def call(*payload)
+      @name == ROLES_DETECT ? mapped_roles(payload) : ability_check(payload)
+    end
+
+    private
+
+    def ability_check(payload)
       @list
         .select { |abilities| abilities.class.valid_role?(*payload) }
         .any? { |abilities| abilities.ability(@name).call(*payload) }
     end
+
+    def mapped_roles(payload)
+      @list.map do |abilities|
+        abilities.class.valid_role?(*payload) ? abilities.class.role_name : nil
+      end.compact
+    end
   end
 end

data/lib/kan/application.rb

@@ -1,16 +1,23 @@
 module Kan
   class Application
-    def initialize(scopes)
+    class InvalidScopeError < StandardError; end
+
+    def initialize(scopes = {})
+      raise(InvalidScopeError) unless scopes.is_a?(Hash)
+      raise(InvalidScopeError) if scopes.empty?
+
       @scopes = Hash(scopes)
+      @abilities_lists = {}
     end
 
     def [](ability)
       scope, ability_name = ability.split('.')
-
       abilities = Array(@scopes[scope.to_sym])
+
       raise_scope_error(scope) if abilities.empty?
+      return @abilities_lists[ability] if @abilities_lists[ability]
 
-      AbilitiesList.new(ability_name, abilities)
+      @abilities_lists[ability] = AbilitiesList.new(ability_name, abilities)
     end
 
     private

data/lib/kan/rspec.rb

@@ -0,0 +1,64 @@
+module Kan
+  module RSpec
+    module Matchers
+      extend ::RSpec::Matchers::DSL
+
+      matcher :permit do |ability, *targets|
+        match_proc = lambda do |app|
+          app[ability].call(*targets)
+        end
+
+        match_when_negated_proc = lambda do |app|
+          !app[ability].call(*targets)
+        end
+
+        failure_message_proc = lambda do |_app|
+          target, action = ability.split('.')
+          "Expected #{target} to grant #{action} but not granted"
+        end
+
+        failure_message_when_negated_proc = lambda do |_app|
+          target, action = ability.split('.')
+          "Expected #{target} not to grant #{action} but granted"
+        end
+
+        match(&match_proc)
+        match_when_negated(&match_when_negated_proc)
+        failure_message(&failure_message_proc)
+        failure_message_when_negated(&failure_message_when_negated_proc)
+      end
+    end
+
+    module DSL
+      def permissions(&block)
+        describe(caller: caller) { instance_eval(&block) }
+      end
+    end
+
+    module AbilityExampleGroup
+      include Kan::RSpec::Matchers
+
+      def self.included(base)
+        base.metadata[:type] = :ability
+        base.extend Kan::RSpec::DSL
+        super
+      end
+    end
+  end
+end
+
+RSpec.configure do |config|
+  if RSpec::Core::Version::STRING.split(".").first.to_i >= 3
+    config.include(
+      Kan::RSpec::AbilityExampleGroup,
+      type: :ability,
+      file_path: %r{spec/abilites}
+    )
+  else
+    config.include(
+      Kan::RSpec::AbilityExampleGroup,
+      type: :ability,
+      example_group: { file_path: %r{spec/abilites} }
+    )
+  end
+end

data/lib/kan/version.rb

@@ -1,3 +1,3 @@
 module Kan
-  VERSION = "0.2.0"
+  VERSION = "0.4.0".freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kan
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Anton Davydov
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-01-21 00:00:00.000000000 Z
+date: 2018-06-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -75,6 +75,7 @@ extra_rdoc_files: []
 files:
 - ".gitignore"
 - ".rspec"
+- ".rubocop.yml"
 - ".travis.yml"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
@@ -83,11 +84,19 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- docs/_config.yml
+- docs/_layouts/default.html
+- docs/faq.md
+- docs/index.md
+- docs/roles.md
+- docs/testing.md
+- docs/working_with_dry.md
 - kan.gemspec
 - lib/kan.rb
 - lib/kan/abilities.rb
 - lib/kan/abilities_list.rb
 - lib/kan/application.rb
+- lib/kan/rspec.rb
 - lib/kan/version.rb
 homepage: https://github.com/davydovanton/kan
 licenses:
@@ -109,7 +118,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.13
+rubygems_version: 2.7.3
 signing_key: 
 specification_version: 4
 summary: Simple, light and functional authorization library