Add directory-based file ownership strategy (#72)

* Add directory-based file ownership

* Rename .codeowners to .codeowner

* Minor version bump

Author: pbomb

README.md

@@ -12,6 +12,18 @@ There is also a [companion VSCode Extension]([url](https://github.com/rubyatscal
 
 There are three ways to declare code ownership using this gem.
 
+### Directory-Based Ownership
+Directory based ownership allows for all files in that directory and all its sub-directories to be owned by one team. To define this, add a `.codeowner` file inside that directory with the name of the team as the contents of that file.
+```
+Team
+```
+
+### File-Annotation Based Ownership
+File annotations are a last resort if there is no clear home for your code. File annotations go at the top of your file, and look like this:
+```ruby
+# @team MyTeam
+```
+
 ### Package-Based Ownership
 Package based ownership integrates [`packwerk`](https://github.com/Shopify/packwerk) and has ownership defined per package. To define that all files within a package are owned by one team, configure your `package.yml` like this:
 ```yml
@@ -38,11 +50,6 @@ owned_globs:
   - app/services/stuff_belonging_to_my_team/**/**
   - app/controllers/other_stuff_belonging_to_my_team/**/**
 ```
-### File-Annotation Based Ownership
-File annotations are a last resort if there is no clear home for your code. File annotations go at the top of your file, and look like this:
-```ruby
-# @team MyTeam
-```
 
 ### Javascript Package Ownership
 Javascript package based ownership allows you to specify an ownership key in a `package.json`. To use this, configure your `package.json` like this:

code_ownership.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |spec|
   spec.name          = 'code_ownership'
-  spec.version       = '1.33.1'
+  spec.version       = '1.34.0'
   spec.authors       = ['Gusto Engineers']
   spec.email         = ['[email protected]']
   spec.summary       = 'A gem to help engineering teams declare ownership of code'

lib/code_ownership/private.rb

@@ -13,6 +13,7 @@
 require 'code_ownership/private/validations/files_have_unique_owners'
 require 'code_ownership/private/ownership_mappers/file_annotations'
 require 'code_ownership/private/ownership_mappers/team_globs'
+require 'code_ownership/private/ownership_mappers/directory_ownership'
 require 'code_ownership/private/ownership_mappers/package_ownership'
 require 'code_ownership/private/ownership_mappers/js_package_ownership'
 require 'code_ownership/private/ownership_mappers/team_yml_ownership'

lib/code_ownership/private/ownership_mappers/directory_ownership.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+# typed: true
+
+module CodeOwnership
+  module Private
+    module OwnershipMappers
+      class DirectoryOwnership
+        extend T::Sig
+        include Mapper
+
+        CODEOWNERS_DIRECTORY_FILE_NAME = '.codeowner'
+
+        @@directory_cache = T.let({}, T::Hash[String, T.nilable(CodeTeams::Team)]) # rubocop:disable Style/ClassVars
+
+        sig do
+          override.params(file: String).
+            returns(T.nilable(::CodeTeams::Team))
+        end
+        def map_file_to_owner(file)
+          map_file_to_relevant_owner(file)
+        end
+
+        sig do
+          override.params(cache: GlobsToOwningTeamMap, files: T::Array[String]).returns(GlobsToOwningTeamMap)
+        end
+        def update_cache(cache, files)
+          globs_to_owner(files)
+        end
+
+        #
+        # Directory ownership ignores the passed in files when generating code owners lines.
+        # This is because Directory ownership knows that the fastest way to find code owners for directory based ownership
+        # is to simply iterate over the directories and grab the owner, rather than iterating over each file just to get what directory it is in
+        # In theory this means that we may generate code owners lines that cover files that are not in the passed in argument,
+        # but in practice this is not of consequence because in reality we never really want to generate code owners for only a
+        # subset of files, but rather we want code ownership for all files.
+        #
+        sig do
+          override.params(files: T::Array[String]).
+            returns(T::Hash[String, ::CodeTeams::Team])
+        end
+        def globs_to_owner(files)
+          # The T.unsafe is because the upstream RBI is wrong for Pathname.glob
+          T
+            .unsafe(Pathname)
+            .glob(File.join('**/', CODEOWNERS_DIRECTORY_FILE_NAME))
+            .map(&:cleanpath)
+            .each_with_object({}) do |pathname, res|
+            owner = owner_for_codeowners_file(pathname)
+            res[pathname.dirname.cleanpath.join('**/**').to_s] = owner
+          end
+        end
+
+        sig { override.returns(String) }
+        def description
+          'Owner in .codeowner'
+        end
+
+        sig { override.void }
+        def bust_caches!
+          @@directory_cache = {} # rubocop:disable Style/ClassVars
+        end
+
+        private
+
+        sig { params(codeowners_file: Pathname).returns(CodeTeams::Team) }
+        def owner_for_codeowners_file(codeowners_file)
+          raw_owner_value = File.foreach(codeowners_file).first.strip
+
+          Private.find_team!(
+            raw_owner_value,
+            codeowners_file.to_s
+          )
+        end
+
+        # takes a file and finds the relevant `.codeowner` file by walking up the directory
+        # structure. Example, given `a/b/c.rb`, this looks for `a/b/.codeowner`, `a/.codeowner`,
+        # and `.codeowner` in that order, stopping at the first file to actually exist.
+        # We do additional caching so that we don't have to check for file existence every time
+        sig { params(file: String).returns(T.nilable(CodeTeams::Team)) }
+        def map_file_to_relevant_owner(file)
+          file_path = Pathname.new(file)
+          path_components = file_path.each_filename.to_a.map { |path| Pathname.new(path) }
+
+          (path_components.length - 1).downto(0).each do |i|
+            potential_relative_path_name = T.must(path_components[0...i]).reduce(Pathname.new('')) { |built_path, path| built_path.join(path) }
+            potential_codeowners_file = potential_relative_path_name.join(CODEOWNERS_DIRECTORY_FILE_NAME)
+
+            potential_codeowners_file_name = potential_codeowners_file.to_s
+
+            team = nil
+            if @@directory_cache.key?(potential_codeowners_file_name)
+              team = @@directory_cache[potential_codeowners_file_name]
+            elsif potential_codeowners_file.exist?
+              team = owner_for_codeowners_file(potential_codeowners_file)
+
+              @@directory_cache[potential_codeowners_file_name] = team
+            else
+              @@directory_cache[potential_codeowners_file_name] = nil
+            end
+
+            return team unless team.nil?
+          end
+
+          nil
+        end
+      end
+    end
+  end
+end

spec/lib/code_ownership/private/ownership_mappers/directory_ownership_spec.rb

@@ -0,0 +1,26 @@
+module CodeOwnership
+  RSpec.describe Private::OwnershipMappers::JsPackageOwnership do
+    describe 'CodeOwnershp.for_file' do
+      before do
+        write_configuration
+
+        write_file('a/b/.codeowner', <<~CONTENTS)
+          Bar
+        CONTENTS
+        write_file('a/b/c/c_file.jsx')
+        write_file('a/b/b_file.jsx')
+        write_file('config/teams/bar.yml', <<~CONTENTS)
+          name: Bar
+        CONTENTS
+      end
+
+      it 'can find the owner of files in team-owned directory' do
+        expect(CodeOwnership.for_file('a/b/b_file.jsx').name).to eq 'Bar'
+      end
+
+      it 'can find the owner of files in a sub-directory of a team-owned directory' do
+        expect(CodeOwnership.for_file('a/b/c/c_file.jsx').name).to eq 'Bar'
+      end
+    end
+  end
+end

spec/lib/code_ownership/private/ownership_mappers/file_annotations_spec.rb

@@ -21,6 +21,9 @@ module CodeOwnership
           ## Team-specific owned globs
           This team owns nothing in this category.
 
+          ## Owner in .codeowner
+          This team owns nothing in this category.
+
           ## Owner metadata key in package.yml
           This team owns nothing in this category.
 

spec/lib/code_ownership/private/ownership_mappers/package_ownership_spec.rb

@@ -30,6 +30,9 @@ module CodeOwnership
           ## Team-specific owned globs
           This team owns nothing in this category.
 
+          ## Owner in .codeowner
+          This team owns nothing in this category.
+
           ## Owner metadata key in package.yml
           - packs/my_other_package/**/**
 

spec/lib/code_ownership/private/ownership_mappers/team_yml_ownership_spec.rb

@@ -17,6 +17,9 @@ module CodeOwnership
           ## Team-specific owned globs
           This team owns nothing in this category.
 
+          ## Owner in .codeowner
+          This team owns nothing in this category.
+
           ## Owner metadata key in package.yml
           This team owns nothing in this category.
 

spec/lib/code_ownership/private/validations/files_have_unique_owners_spec.rb

@@ -17,6 +17,10 @@ module CodeOwnership
             // @team Bar
           CONTENTS
 
+          write_file('frontend/javascripts/packages/my_package/.codeowner', <<~CONTENTS)
+            Bar
+          CONTENTS
+
           write_file('frontend/javascripts/packages/my_package/package.json', <<~CONTENTS)
             {
               "name": "@gusto/my_package",
@@ -52,8 +56,8 @@ module CodeOwnership
             expect(e.message).to eq <<~EXPECTED.chomp
               Code ownership should only be defined for each file in one way. The following files have declared ownership in multiple ways.
 
-              - frontend/javascripts/packages/my_package/owned_file.jsx (Annotations at the top of file, Team-specific owned globs, Owner metadata key in package.json)
-              - frontend/javascripts/packages/my_package/package.json (Team-specific owned globs, Owner metadata key in package.json)
+              - frontend/javascripts/packages/my_package/owned_file.jsx (Annotations at the top of file, Team-specific owned globs, Owner in .codeowner, Owner metadata key in package.json)
+              - frontend/javascripts/packages/my_package/package.json (Team-specific owned globs, Owner in .codeowner, Owner metadata key in package.json)
               - packs/my_pack/owned_file.rb (Annotations at the top of file, Team-specific owned globs, Owner metadata key in package.yml)
               - packs/my_pack/package.yml (Team-specific owned globs, Owner metadata key in package.yml)
 

spec/lib/code_ownership/private/validations/github_codeowners_up_to_date_spec.rb

@@ -51,6 +51,9 @@ module CodeOwnership
               /app/services/bar_stuff/** @MyOrg/bar-team
               /frontend/javascripts/bar_stuff/** @MyOrg/bar-team
 
+              # Owner in .codeowner
+              /directory/owner/**/** @MyOrg/bar-team
+
               # Owner metadata key in package.yml
               /packs/my_other_package/**/** @MyOrg/bar-team
 
@@ -85,6 +88,9 @@ module CodeOwnership
                 /app/services/bar_stuff/** @MyOrg/bar-team
                 /frontend/javascripts/bar_stuff/** @MyOrg/bar-team
 
+                # Owner in .codeowner
+                /directory/owner/**/** @MyOrg/bar-team
+
                 # Owner metadata key in package.yml
                 /packs/my_other_package/**/** @MyOrg/bar-team
 
@@ -159,6 +165,9 @@ module CodeOwnership
                 # /app/services/bar_stuff/** @MyOrg/bar-team
                 # /frontend/javascripts/bar_stuff/** @MyOrg/bar-team
 
+                # Owner in .codeowner
+                # /directory/owner/**/** @MyOrg/bar-team
+
                 # Owner metadata key in package.yml
                 # /packs/my_other_package/**/** @MyOrg/bar-team
 
@@ -327,6 +336,8 @@ module CodeOwnership
 
                 CODEOWNERS should contain the following lines, but does not:
                 - "/packs/my_pack/owned_file.rb @MyOrg/bar-team"
+                - "# Owner in .codeowner"
+                - "/directory/owner/**/** @MyOrg/bar-team"
                 - "# Owner metadata key in package.yml"
                 - "/packs/my_other_package/**/** @MyOrg/bar-team"
 
@@ -364,6 +375,9 @@ module CodeOwnership
               /app/services/bar_stuff/** @MyOrg/bar-team
               /frontend/javascripts/bar_stuff/** @MyOrg/bar-team
 
+              # Owner in .codeowner
+              /directory/owner/**/** @MyOrg/bar-team
+
               # Owner metadata key in package.yml
               /packs/my_other_package/**/** @MyOrg/bar-team
 
@@ -429,6 +443,8 @@ module CodeOwnership
 
                 CODEOWNERS should contain the following lines, but does not:
                 - "/packs/my_pack/owned_file.rb @MyOrg/bar-team"
+                - "# Owner in .codeowner"
+                - "/directory/owner/**/** @MyOrg/bar-team"
                 - "# Owner metadata key in package.yml"
                 - "/packs/my_other_package/**/** @MyOrg/bar-team"
 
@@ -457,6 +473,9 @@ module CodeOwnership
               /frontend/javascripts/packages/my_package/owned_file.jsx @MyOrg/bar-team
               /packs/my_pack/owned_file.rb @MyOrg/bar-team
 
+              # Owner in .codeowner
+              /directory/owner/**/** @MyOrg/bar-team
+
               # Owner metadata key in package.yml
               /packs/my_other_package/**/** @MyOrg/bar-team
 
@@ -495,6 +514,9 @@ module CodeOwnership
               /packs/my_pack/owned_file.rb @MyOrg/bar-team
               /frontend/javascripts/packages/my_package/owned_file.jsx @MyOrg/bar-team
 
+              # Owner in .codeowner
+              /directory/owner/**/** @MyOrg/bar-team
+
               # Owner metadata key in package.yml
               /packs/my_other_package/**/** @MyOrg/bar-team