owners 0.0.8 → 0.0.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5b6b42791dcd2801448725619a34e70091c5d84b
-  data.tar.gz: dca77d4996a6a2e9e0fedf15a4b86308f37b5187
+  metadata.gz: 20bc5ff50e8b6c0614a56bf72251c9dc8a1d059c
+  data.tar.gz: a765f585fde8b708ee5ff77c3214af251eff0407
 SHA512:
-  metadata.gz: 1c40ac244b5ff0bf3aa6c7a465a09291a784bfd97a9f8c5c3cdd8719581e6d9e6583defe885a1d69819a16d75daf7eaeda5fef755a597a4f52b1cab490585c94
-  data.tar.gz: 124a7bfa90f7aa4b59cc241d9b9da38053aca59e41735768972aca871fe21a936097dabef27af8b7d12134e3d0a96a09ba8c8e5bb856133ba8f9ddac06c09b8b
+  metadata.gz: 6ccafca0dd0655c27e80103e06f7cc61dce514bb1f8c556b048851de1eddb43752db874eb331c85ec64d499fb620368b2d503376040d5eb1375bc80b24013e5e
+  data.tar.gz: bfbd3c7370a857c1c090b2332e42ae1ff7007c7c4322ba992c168afb34fa6e2bd43ca56a442750fb5335a8e208ee77e275c7c2d217b11e11ad12915ceea49de2

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    owners (0.0.8)
+    owners (0.0.9)
       thor
 
 GEM

data/README.md

@@ -34,6 +34,8 @@ jane@your-org.com
 #some_slack_channel
 ```
 
+#### Filters
+
 The `OWNERS` file also supports filtering paths with regular expressions. Any whitespace between these filters and their corresponding subscribers is ignored.
 
 ```
@@ -43,6 +45,8 @@ bob@demo.com  lib/bobs_special_file.rb
 #whitespace   path/with spaces/is all part/of the filter.txt
 ```
 
+#### Multiple subscribers
+
 Subscribers can be listed multiple times in an `OWNERS` file.
 
 ```
@@ -56,6 +60,8 @@ Multiple comma separated subscribers can be listed for the same filter.
 @data,@team-leads db
 ```
 
+#### Comments
+
 Comments are supported by prefixing lines with `//`.
 
 ```
@@ -64,14 +70,61 @@ Comments are supported by prefixing lines with `//`.
   // even this one with whitespace
 
 @data,@team-leads db
+
+#internal .env
 ```
 
+#### Finding owners
+
 Find the owners for specific files by passing them to the `Owners.for` method.
+This returns an array of `Owner` objects which are simple wrappers around
+`String` with a few extra methods.
 
 ```ruby
-Owners.for("app/models/user.rb", "db/schema.rb") #=> ["@data", "@team-leads"]
+owners = Owners.for("db/schema.rb", ".env") #=> ["@data", "#internal"]
+```
+
+The owner's `type` can be one of `%i(alert email group label mention path tag)`.
+
+```ruby
+owners.first.type #=> :mention
+owners.last.type  #=> :tag
+```
+
+The `paths` method returns an array of owned file paths that triggered the match.
+
+```ruby
+owners.first.paths #=> ["db/schema.rb"]
+owners.last.paths  #=> [".env"]
+```
+
+The `subscriptions` method allows us to inspect the rules that triggered a match.
+
+```ruby
+owners.each do |owner|
+  puts owner
+
+  owner.subscriptions.each do |path, subscriptions|
+    puts "  #{path}"
+
+    subscriptions.each do |subscription|
+      puts "  #{subscription.file}:#{subscription.line} => #{subscription.filter}"
+    end
+  end
+end
 ```
 
+```
+@data
+  db/schema.rb
+  OWNERS:5 => (?-mix:db)
+#internal
+  .env
+  OWNERS:7 => (?-mix:.env)
+```
+
+#### Git diff integration
+
 To find the owners for files changed with `git diff` use the `Owners.for_diff` method.
 
 ```ruby
@@ -79,20 +132,50 @@ Owners.for_diff("your-feature-branch-or-ref", "optional-base-ref-defaults-to-mas
 ```
 
 
-## CLI
+## Command line interface
 
-This gem also comes with a convenient `owners` command line interface. Each owner is printed out and separated by newlines.
+This gem also comes with a convenient `owners` CLI. Each owner is printed out and separated by newlines.
 
 ```bash
 owners for .env app/controllers/posts_controller.rb app/models/user.rb
 ```
 
 ```
-@infrastructure
-@api
+#infrastructure
+@api/internal
+@data
+```
+
+#### Debugging and managing subscriptions
+
+The `--debug` option outputs additional information for subscriptions.
+
+```bash
+owners for --debug .env app/controllers/posts_controller.rb app/models/user.rb
+```
+
+```
+#infrastructure
+tag
+  .env
+  OWNERS:1 => (?-mix:\.env)
+
+@api/internal
+group
+  app/controllers/posts_controller.rb
+  OWNERS:2 => (?-mix:app/(controllers|models))
+
+  app/models/user.rb
+  OWNERS:2 => (?-mix:app/(controllers|models))
+
 @data
+mention
+  ./app/models/user.rb
+  ./OWNERS:3 => (?-mix:app/models)
 ```
 
+#### Git diff integration
+
 The `git diff` integration works in the command line as well.
 
 ```bash
@@ -110,6 +193,16 @@ See `owners help` for more information.
 * `Owners.file=`
 * `Owners.for`
 * `Owners.for_diff`
+* `Owners::Owner#type`
+* `Owners::Owner#subscriptions`
+* `Owners::Subscription#file`
+* `Owners::Subscription#filter`
+* `Owners::Subscription#line`
+* `Owners::Subscription#metadata?`
+* `Owners::Subscription#root`
+* `Owners::Subscription#subscribed?`
+* `Owners::Subscription#subscribers`
+* `Owners::Subscription#subscription`
 
 
 ## Testing
@@ -130,4 +223,4 @@ bundle exec rspec
 
 ## License
 
-[MIT](https://github.com/shuber/owners/blob/master/LICENSE)  - Copyright © 2015 Sean Huber
+[MIT](https://github.com/shuber/owners/blob/master/LICENSE) - Copyright © 2015 Sean Huber

data/example/OWNERS

@@ -1,6 +1,6 @@
 // comment
 @org/blog
-@multiple,@owners db
+,,,@multiple,@owners,, db
 //comment
 
 ////// comment

data/lib/owners/cli.rb

@@ -1,20 +1,47 @@
 module Owners
   class CLI < Thor
+    class_option :debug,
+      aliases: %w(-d),
+      desc: "Output additional subscription debugging info",
+      type: :boolean
+
+    class_option :file,
+      aliases: %w(-f),
+      desc: "The name of the OWNERS file",
+      type: :string
+
     desc "for [FILES...]", "List owners for a set of files"
-    method_option :file, desc: "The name of the OWNERS file"
     def for(*files)
       Owners.file = options[:file] if options[:file]
       Owners.for(*files).each do |owner|
-        puts owner
+        output(owner)
       end
     end
 
     desc "for_diff REF [BASE_REF]", "List owners for a set of git changes"
-    method_option :file, desc: "The name of the OWNERS file"
     def for_diff(ref, base_ref = "master")
       Owners.file = options[:file] if options[:file]
       Owners.for_diff(ref, base_ref).each do |owner|
-        puts owner
+        output(owner)
+      end
+    end
+
+    no_commands do
+      def output(owner)
+        say owner
+
+        if options[:debug]
+          say owner.type, :yellow
+
+          owner.subscriptions.each do |path, subscriptions|
+            subscriptions.each do |sub|
+              say "  #{path}", :red
+              say "  #{sub.file}:#{sub.line} => #{sub.filter}", :blue
+            end
+
+            say
+          end
+        end
       end
     end
   end

data/lib/owners/config.rb

@@ -1,50 +1,50 @@
 module Owners
-  # Parses an OWNERS file and returns an array of owners
-  # that have subscribed to a specified file path.
+  # Represents a single OWNERS file.
+  #
+  # It parses OWNERS files and returns an array of
+  # {Subscription} objects is returned for a specified
+  # file path.
   #
   # @api private
   class Config
-    COMMENT = /^\s*\/\//
+    attr_reader :file, :root
+
+    def self.for(configs)
+      configs.map do |file, contents|
+        new(file, contents)
+      end
+    end
 
     def initialize(file, contents = nil)
+      @file = file.to_s
       @contents = contents || file.read
-      @root = File.dirname(file.to_s)
+      @root = File.dirname(@file)
     end
 
-    def owners(path)
-      if path =~ prefix
-        relative = path.sub(prefix, "")
-
-        search do |subscription, results|
-          owners = subscribers(relative, subscription)
-          results.push(*owners)
+    def subscriptions(path)
+      search do |subscription, results|
+        if subscription.subscribed?(path)
+          results << subscription
         end
       end
     end
 
     private
 
-    def prefix
-      /\.?\/?#{@root}\//
-    end
-
     def search(&block)
-      subscriptions.each_with_object([], &block)
+      attempts
+        .reject(&:metadata?)
+        .each_with_object([], &block)
     end
 
-    def subscriptions
-      @contents.split("\n").reject do |subscription|
-        subscription.empty? || subscription =~ COMMENT
+    def attempts
+      lines.map.with_index do |subscription, index|
+        Subscription.new(subscription, index + 1, self)
       end
     end
 
-    def subscribers(path, subscription)
-      subscribers, pattern = subscription.split(/\s+/, 2)
-      regex = Regexp.new(pattern || ".*")
-
-      subscribers.split(",").tap do |owners|
-        owners.clear unless regex =~ path
-      end
+    def lines
+      @contents.split("\n")
     end
   end
 end

data/lib/owners/owner.rb

@@ -0,0 +1,36 @@
+module Owners
+  # Represents a unique "owner" across any number of OWNERS files.
+  #
+  # It is a simple wrapper around a {String} with some useful
+  # methods for inspecting an owner's type and subscriptions.
+  #
+  # @api public
+  class Owner < SimpleDelegator
+    def paths
+      subscriptions.keys
+    end
+
+    def subscriptions
+      @subscriptions ||= Hash.new { |hash, key| hash[key] = [] }
+    end
+
+    def type
+      case to_s
+      when /^!/
+        :alert
+      when /^[\w+\-.]+@[a-z\d\-]+(\.[a-z]+)*\.[a-z]+$/i
+        :email
+      when /^@.+\/[^@]+$/
+        :group
+      when /^@/
+        :mention
+      when /^#/
+        :tag
+      when /\//
+        :path
+      else
+        :label
+      end
+    end
+  end
+end

data/lib/owners/search.rb

@@ -1,40 +1,67 @@
 module Owners
   # Accepts an array of file paths and returns an array of
-  # owners that have subscribed to the specified files.
+  # {Owner} objects that have subscribed to the files.
   #
   # @api private
   class Search
+    RELATIVE = /^\.?\//
+
     def initialize(files, configs = nil)
       @files = files.map(&:dup)
       @configs = configs
     end
 
-    def owners
-      search do |(path, config), results|
-        owners = config.owners(path.to_s)
-        results.merge(owners) if owners
+    def results
+      owners.each do |owner|
+        subscriptions.each do |path, subscription|
+          if subscription.subscribers.include?(owner)
+            owner.subscriptions[path] << subscription
+          end
+        end
       end
     end
 
     private
 
+    def owners
+      subscribers.map { |subscriber| Owner.new(subscriber) }
+    end
+
+    def subscribers
+      subscriptions_by_file
+        .values
+        .flatten
+        .flat_map(&:subscribers)
+        .uniq
+    end
+
+    def subscriptions
+      subscriptions_by_file.flat_map do |path, subscriptions|
+        [path].product(subscriptions)
+      end
+    end
+
+    def subscriptions_by_file
+      search do |(path, config), results|
+        relative = path.sub("./", "")
+        results[relative] += config.subscriptions(path)
+      end
+    end
+
     def search(&block)
-      attempts.each_with_object(SortedSet.new, &block).to_a
+      results = Hash.new { |hash, key| hash[key] = [] }
+      attempts.each_with_object(results, &block)
     end
 
     def attempts
-      paths.product(configs)
+      paths.map(&:to_s).product(configs)
     end
 
     def configs
-      if @configs
-        @configs.map { |file, contents| Config.new(file, contents) }
-      else
-        subscriptions.map { |file| Config.new(file) }
-      end
+      Config.for(@configs || owner_files)
     end
 
-    def subscriptions
+    def owner_files
       trees.flat_map(&:owner_files).uniq
     end
 
@@ -44,7 +71,7 @@ module Owners
 
     def paths
       @files.map do |file|
-        file.prepend("./") unless file =~ /^\.?\//
+        file.prepend("./") unless file =~ RELATIVE
         Pathname.new(file)
       end
     end

data/lib/owners/subscription.rb

@@ -0,0 +1,57 @@
+module Owners
+  # Represents a single line of an OWNERS file.
+  #
+  # It contains some useful methods for inspecting the
+  # subscriptions themselves like the file, line, and
+  # filter, and subscribers.
+  #
+  # @api public
+  class Subscription
+    COMMENT = /^\s*\/\//
+    WILDCARD = /.*/
+
+    attr_reader :file, :line, :root, :subscription
+
+    def initialize(subscription, line, config)
+      @subscribers, @filter = subscription.split(/\s+/, 2)
+      @subscription = subscription
+      @line = line
+      @file = config.file.sub("./", "")
+      @root = config.root
+    end
+
+    def filter
+      Regexp.new(@filter || WILDCARD)
+    end
+
+    def metadata?
+      comment? || empty?
+    end
+
+    def subscribed?(path)
+      path =~ prefix && relative(path) =~ filter
+    end
+
+    def subscribers
+      @subscribers.split(",").reject(&:empty?)
+    end
+
+    private
+
+    def comment?
+      subscription =~ COMMENT
+    end
+
+    def empty?
+      subscription.strip.empty?
+    end
+
+    def prefix
+      /\.?\/?#{root}\//
+    end
+
+    def relative(path)
+      path.sub(prefix, "")
+    end
+  end
+end

data/lib/owners/version.rb

@@ -1,3 +1,3 @@
 module Owners
-  VERSION = "0.0.8"
+  VERSION = "0.0.9"
 end

data/lib/owners.rb

@@ -1,9 +1,12 @@
+require "delegate"
 require "pathname"
 require "set"
 require "thor"
 require_relative "owners/cli"
 require_relative "owners/config"
+require_relative "owners/owner"
 require_relative "owners/search"
+require_relative "owners/subscription"
 require_relative "owners/tree"
 require_relative "owners/version"
 
@@ -25,7 +28,7 @@ module Owners
     #
     # @api public
     def for(*files)
-      Search.new(files).owners
+      Search.new(files).results
     end
 
     # Accepts a git ref and an optional base ref and returns
@@ -47,7 +50,7 @@ module Owners
         hash.update(file => contents)
       end
 
-      Search.new(files, configs).owners
+      Search.new(files, configs).results
     end
   end
 end

data/spec/owner_spec.rb

@@ -0,0 +1,75 @@
+RSpec.describe Owners::Owner do
+  describe "#paths" do
+    subject { described_class.new("test") }
+
+    it "parses paths correctly" do
+      expect(subject.paths).to be_empty
+
+      subject.subscriptions["testing"] << nil
+      expect(subject.paths).to eq(["testing"])
+
+      subject.subscriptions["again"] << nil
+      expect(subject.paths).to eq(["testing", "again"])
+    end
+  end
+
+  describe "#type" do
+    subject { described_class.new(owner).type }
+
+    context "with an alert" do
+      let(:owner) { "!alert" }
+
+      it "parses type correctly" do
+        expect(subject).to eq(:alert)
+      end
+    end
+
+    context "with an email" do
+      let(:owner) { "test+extra@example.com" }
+
+      it "parses type correctly" do
+        expect(subject).to eq(:email)
+      end
+    end
+
+    context "with a group" do
+      let(:owner) { "@example/group-name" }
+
+      it "parses type correctly" do
+        expect(subject).to eq(:group)
+      end
+    end
+
+    context "with a mention" do
+      let(:owner) { "@test" }
+
+      it "parses type correctly" do
+        expect(subject).to eq(:mention)
+      end
+    end
+
+    context "with a tag" do
+      let(:owner) { "#test" }
+
+      it "parses type correctly" do
+        expect(subject).to eq(:tag)
+      end
+    end
+
+    context "with a path" do
+      let(:owner) { "/one/two" }
+
+      it "parses type correctly" do
+        expect(subject).to eq(:path)
+      end
+    end
+
+    context "with anything else" do
+      let(:owner) { "anything" }
+
+      it "parses type correctly" do
+        expect(subject).to eq(:label)
+      end
+    end
+  end
+end

data/spec/owners_cli_spec.rb

@@ -22,7 +22,7 @@ RSpec.describe Owners::CLI do
     end
 
     context "with a specified file" do
-      before { args << "--file" << "SOMETHING_ELSE" }
+      before { args << "-f" << "SOMETHING_ELSE" }
 
       it "overrides the default OWNERS filename" do
         begin
@@ -32,6 +32,27 @@ RSpec.describe Owners::CLI do
         end
       end
     end
+
+    context "without debugging" do
+      before { args << "-d" }
+
+      it "parses owners correctly" do
+        expected = <<-OUTPUT
+@org/auth
+group
+  example/app/controllers/users_controller.rb
+  example/app/OWNERS:1 => (?-mix:user)
+
+@org/blog
+group
+  example/app/controllers/users_controller.rb
+  example/OWNERS:2 => (?-mix:.*)
+
+        OUTPUT
+
+        expect(subject).to eq(expected)
+      end
+    end
   end
 
   describe "for_diff" do
@@ -39,7 +60,7 @@ RSpec.describe Owners::CLI do
 
     context "without a specified file" do
       it "parses owners correctly" do
-        expect(subject).to eq("@org/blog\n@whitespace\ndata@example.com\n")
+        expect(subject).to eq("@org/blog\ndata@example.com\n@whitespace\n")
       end
     end
 

data/spec/owners_spec.rb

@@ -17,7 +17,7 @@ RSpec.describe Owners do
       ]}
 
       it "parses owners correctly" do
-        expect(subject).to eq(["@org/auth", "@org/blog", "data@example.com"])
+        expect(subject).to eq(["@org/blog", "@org/auth", "data@example.com"])
       end
     end
 
@@ -41,7 +41,7 @@ RSpec.describe Owners do
       let(:paths) { ["example/app/models/blog.rb"] }
 
       it "parses owners correctly" do
-        expect(subject).to eq(["@blogger", "@org/blog", "data@example.com"])
+        expect(subject).to eq(["data@example.com", "@blogger", "@org/blog"])
       end
     end
 
@@ -49,7 +49,7 @@ RSpec.describe Owners do
       let(:paths) { ["example/app/models/post.rb"] }
 
       it "parses owners correctly" do
-        expect(subject).to eq(["@org/blog", "@whitespace", "data@example.com"])
+        expect(subject).to eq(["data@example.com", "@whitespace", "@org/blog"])
       end
     end
 
@@ -57,7 +57,7 @@ RSpec.describe Owners do
       let(:paths) { ["example/app/models/comment.rb"] }
 
       it "parses owners correctly" do
-        expect(subject).to eq(["@duplicate", "@org/blog", "@owner", "data@example.com"])
+        expect(subject).to eq(["data@example.com", "@owner", "@duplicate", "@org/blog"])
       end
     end
 
@@ -65,7 +65,15 @@ RSpec.describe Owners do
       let(:paths) { ["example/db/schema.rb"] }
 
       it "parses owners correctly" do
-        expect(subject).to eq(["@multiple", "@org/blog", "@owners"])
+        expect(subject).to eq(["@org/blog", "@multiple", "@owners"])
+      end
+    end
+
+    context "with empty comma separated owners" do
+      let(:paths) { ["example/db/schema.rb"] }
+
+      it "parses owners correctly" do
+        expect(subject).to eq(["@org/blog", "@multiple", "@owners"])
       end
     end
 
@@ -95,7 +103,7 @@ RSpec.describe Owners do
       let(:base_ref) { "ba7cd78" }
 
       it "parses owners correctly" do
-        expect(subject).to eq(["@org/blog", "@whitespace", "data@example.com"])
+        expect(subject).to eq(["@org/blog", "data@example.com", "@whitespace"])
       end
     end
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: owners
 version: !ruby/object:Gem::Version
-  version: 0.0.8
+  version: 0.0.9
 platform: ruby
 authors:
 - Sean Huber
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-02-20 00:00:00.000000000 Z
+date: 2016-03-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -68,10 +68,13 @@ files:
 - lib/owners.rb
 - lib/owners/cli.rb
 - lib/owners/config.rb
+- lib/owners/owner.rb
 - lib/owners/search.rb
+- lib/owners/subscription.rb
 - lib/owners/tree.rb
 - lib/owners/version.rb
 - owners.gemspec
+- spec/owner_spec.rb
 - spec/owners_cli_spec.rb
 - spec/owners_spec.rb
 - spec/spec_helper.rb
@@ -105,6 +108,7 @@ signing_key:
 specification_version: 4
 summary: Take ownership of your code
 test_files:
+- spec/owner_spec.rb
 - spec/owners_cli_spec.rb
 - spec/owners_spec.rb
 - spec/spec_helper.rb