code_ownership 1.28.0 → 1.29.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d73cb8995d6430d05780252417863b38bd14a461bf8f3afe4b9724abb407efea
-  data.tar.gz: 7cc3c3c4a2968b8e3a265f990c28395b0c4e6163b7ba48ad2b0c8be64123990c
+  metadata.gz: 8008aad63593c3be910dc1e7f45f2518150d0e76a92f8a021279902995499402
+  data.tar.gz: 551585001712db071af3e33607bfd121ff48524fa66776f8ee48a299da28ef1a
 SHA512:
-  metadata.gz: 6f2a2c2331aa980b414343e54429ba3ab367fa6a38cdad44811b84193afd8a6d3846baf77ae8b7cd78a2754b65865b5799644382ff5182ba0439bb3cb3884cf6
-  data.tar.gz: d0ecc33dd542a3dc606caceb52fb38ed32743a12076f5253b96a2c2c6b7fa24a0b1445df6d1a41878ef350a87fe5075cbb17ebc5bb3964211cbac18ee005bfd5
+  metadata.gz: a2b94a65f309e158505b6dd4aa740cf3cfedc7076d9ccb0e7fbc1fe04ce147c8355cbe9cfd687a6b0e05e5ad755bb703f8fc1b530ad40f9b24fb9a4d8326a18f
+  data.tar.gz: 895352504690505cce06da848c5a400b3e48f1a9e10d49baa5a1e0093bd29c70c6042eaaa9c21dea14cbe8b0e7e44d15a8bf124150528f33280abee5eb101d97

data/README.md

@@ -1,14 +1,17 @@
 # CodeOwnership
-This gem helps engineering teams declare ownership of code.
 
-Check out `lib/code_ownership.rb` to see the public API.
+This gem helps engineering teams declare ownership of code. This gem works best in large, usually monolithic code bases where many teams work together.
 
-Check out `code_ownership_spec.rb` to see examples of how code ownership is used.
+Check out [`lib/code_ownership.rb`](https://github.com/rubyatscale/code_ownership/blob/main/lib/code_ownership.rb) to see the public API.
+
+Check out [`code_ownership_spec.rb`](https://github.com/rubyatscale/code_ownership/blob/main/spec/lib/code_ownership_spec.rb) to see examples of how code ownership is used.
 
 There is also a [companion VSCode Extension]([url](https://github.com/rubyatscale/code-ownership-vscode)) for this gem. Just search `Gusto.code-ownership-vscode` in the VSCode Extension Marketplace.
 
 ## Usage: Declaring Ownership
+
 There are three ways to declare code ownership using this gem.
+
 ### 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
@@ -31,6 +34,29 @@ File annotations are a last resort if there is no clear home for your code. File
 ```ruby
 # @team MyTeam
 ```
+
+### Javascript Package Ownership
+Javascript package based ownership allows you to specify an owenrship key in a `package.json`. To use this, configure your `package.json` like this:
+
+```json
+{
+  // other keys
+  "metadata": {
+    "owner": "My Team"
+  }
+  // other keys
+}
+```
+
+You can also tell `code_ownership` where to find JS packages in the configuration, like this:
+```yml
+js_package_paths:
+  - frontend/javascripts/packages/*
+  - frontend/other_location_for_packages/*
+```
+
+This defaults `**/`, which makes it look for `package.json` files across your application.
+
 ## Usage: Reading CodeOwnership
 ### `for_file`
 `CodeOwnership.for_file`, given a relative path to a file returns a `CodeTeams::Team` if there is a team that owns the file, `nil` otherwise.
@@ -66,12 +92,25 @@ Under the hood, this finds the file where the class is defined and returns the o
 
 See `code_ownership_spec.rb` for an example.
 
+### `for_team`
+`CodeOwnership.for_team` can be used to generate an ownership report for a team.
+```ruby
+CodeOwnership.for_team('My Team')
+```
+
+You can shovel this into a markdown file for easy viewing using the CLI:
+```
+bin/codeownership for_team 'My Team' > tmp/ownership_report.md
+```
+
 ## Usage: Generating a `CODEOWNERS` file
 
 A `CODEOWNERS` file defines who owns specific files or paths in a repository. When you run `bin/codeownership validate`, a `.github/CODEOWNERS` file will automatically be generated and updated.
 
 ## Proper Configuration & Validation
+
 CodeOwnership comes with a validation function to ensure the following things are true:
+
 1) Only one mechanism is defining file ownership. That is -- you can't have a file annotation on a file owned via package-based or glob-based ownership. This helps make ownership behavior more clear by avoiding concerns about precedence.
 2) All teams referenced as an owner for any file or package is a valid team (i.e. it's in the list of `CodeTeams.all`).
 3) All files have ownership. You can specify in `unowned_globs` to represent a TODO list of files to add ownership to.

data/lib/code_ownership/cli.rb

@@ -11,6 +11,8 @@ module CodeOwnership
         validate!(argv)
       elsif command == 'for_file'
         for_file(argv)
+      elsif command == 'for_team'
+        for_team(argv)
       elsif [nil, "help"].include?(command)
         puts <<~USAGE
           Usage: bin/codeownership <subcommand>
@@ -18,6 +20,7 @@ module CodeOwnership
           Subcommands:
             validate - run all validations
             for_file - find code ownership for a single file
+            for_team - find code ownership information for a team
             help  - display help information about code_ownership
         USAGE
       else
@@ -116,6 +119,28 @@ module CodeOwnership
       end
     end
 
+    def self.for_team(argv)
+      options = {}
+
+      parser = OptionParser.new do |opts|
+        opts.banner = 'Usage: bin/codeownership for_team \'Team Name\''
+
+        opts.on('--help', 'Shows this prompt') do
+          puts opts
+          exit
+        end
+      end
+      teams = argv.select { |arg| !arg.start_with?('--') }
+      args = parser.order!(argv) {}
+      parser.parse!(args)
+
+      if teams.count != 1
+        raise "Please pass in one team. Use `bin/codeownership for_team --help` for more info"
+      end
+      
+      puts CodeOwnership.for_team(teams.first)
+    end
+
     private_class_method :validate!
   end
 end

data/lib/code_ownership/private/ownership_mappers/package_ownership.rb

@@ -16,7 +16,7 @@ module CodeOwnership
             returns(T.nilable(::CodeTeams::Team))
         end
         def map_file_to_owner(file)
-          package = map_file_to_relevant_package(file)
+          package = ParsePackwerk.package_from_path(file)
 
           return nil if package.nil?
 
@@ -80,41 +80,6 @@ module CodeOwnership
         def bust_caches!
           @@package_yml_cache = {} # rubocop:disable Style/ClassVars
         end
-
-        private
-
-        # takes a file and finds the relevant `package.yml` file by walking up the directory
-        # structure. Example, given `packs/a/b/c.rb`, this looks for `packs/a/b/package.yml`, `packs/a/package.yml`,
-        # `packs/package.yml`, and `package.yml` 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(ParsePackwerk::Package)) }
-        def map_file_to_relevant_package(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_package_yml_path = potential_relative_path_name.
-              join(ParsePackwerk::PACKAGE_YML_NAME)
-
-            potential_package_yml_string = potential_package_yml_path.to_s
-
-            package = nil
-            if @@package_yml_cache.key?(potential_package_yml_string)
-              package = @@package_yml_cache[potential_package_yml_string]
-            elsif potential_package_yml_path.exist?
-              package = ParsePackwerk::Package.from(potential_package_yml_path)
-
-              @@package_yml_cache[potential_package_yml_string] = package
-            else
-              @@package_yml_cache[potential_package_yml_string] = nil
-            end
-
-            return package unless package.nil?
-          end
-
-          nil
-        end
       end
     end
   end

data/lib/code_ownership/private/parse_js_packages.rb

@@ -32,6 +32,16 @@ module CodeOwnership
             name: package_name,
             metadata: package_loaded_json[METADATA] || {}
           )
+        rescue JSON::ParserError => e
+          error_message = <<~MESSAGE
+            #{e.inspect}
+
+            #{pathname} has invalid JSON, so code ownership cannot be determined.
+
+            Please either make the JSON in that file valid or specify `js_package_paths` in config/code_ownership.yml.
+          MESSAGE
+
+          raise InvalidCodeOwnershipConfigurationError.new(error_message)
         end
 
         sig { returns(Pathname) }

data/lib/code_ownership.rb

@@ -35,6 +35,36 @@ module CodeOwnership
     @for_file[file] = owner
   end
 
+  sig { params(team: T.any(CodeTeams::Team, String)).returns(String) }
+  def for_team(team)
+    team = T.must(CodeTeams.find(team)) if team.is_a?(String)
+    ownership_information = T.let([], T::Array[String])
+
+    ownership_information << "# Code Ownership Report for `#{team.name}` Team"
+    Private.mappers.each do |mapper|
+      ownership_information << "## #{mapper.description}"
+      codeowners_lines = mapper.codeowners_lines_to_owners
+      ownership_for_mapper = []
+      codeowners_lines.each do |line, team_for_line|
+        next if team_for_line.nil?
+        if team_for_line.name == team.name
+          ownership_for_mapper << "- #{line}"
+        end
+      end
+
+      if ownership_for_mapper.empty?
+        ownership_information << 'This team owns nothing in this category.'
+      else
+        ownership_information += ownership_for_mapper
+      end
+
+      
+      ownership_information << ""
+    end
+
+    ownership_information.join("\n")
+  end
+
   class InvalidCodeOwnershipConfigurationError < StandardError
   end
 

data/sorbet/config

@@ -1,4 +1,5 @@
 --dir
 .
 --ignore=/spec
+--ignore=/vendor/bundle
 --enable-experimental-requires-ancestor

data/sorbet/rbi/gems/{parse_packwerk@0.7.0.rbi → parse_packwerk@0.12.0.rbi}

@@ -6,12 +6,18 @@
 
 module ParsePackwerk
   class << self
-    sig { params(package_yml_pathnames: T.nilable(T::Array[::Pathname])).returns(T::Array[::ParsePackwerk::Package]) }
-    def all(package_yml_pathnames: T.unsafe(nil)); end
+    sig { returns(T::Array[::ParsePackwerk::Package]) }
+    def all; end
+
+    sig { void }
+    def bust_cache!; end
 
     sig { params(name: ::String).returns(T.nilable(::ParsePackwerk::Package)) }
     def find(name); end
 
+    sig { params(file_path: T.any(::Pathname, ::String)).returns(T.nilable(::ParsePackwerk::Package)) }
+    def package_from_path(file_path); end
+
     sig { params(package: ::ParsePackwerk::Package).void }
     def write_package_yml!(package); end
 
@@ -27,12 +33,24 @@ end
 
 class ParsePackwerk::Configuration < ::T::Struct
   const :exclude, T::Array[::String]
+  const :package_paths, T::Array[::String]
 
   class << self
+    sig { params(config_hash: T::Hash[T.untyped, T.untyped]).returns(T::Array[::String]) }
+    def excludes(config_hash); end
+
+    sig { returns(::ParsePackwerk::Configuration) }
+    def fetch; end
+
     def inherited(s); end
+
+    sig { params(config_hash: T::Hash[T.untyped, T.untyped]).returns(T::Array[::String]) }
+    def package_paths(config_hash); end
   end
 end
 
+ParsePackwerk::DEFAULT_EXCLUDE_GLOBS = T.let(T.unsafe(nil), Array)
+ParsePackwerk::DEFAULT_PACKAGE_PATHS = T.let(T.unsafe(nil), Array)
 ParsePackwerk::DEPENDENCIES = T.let(T.unsafe(nil), String)
 ParsePackwerk::DEPRECATED_REFERENCES_YML_NAME = T.let(T.unsafe(nil), String)
 
@@ -91,6 +109,23 @@ class ParsePackwerk::Package < ::T::Struct
   end
 end
 
+class ParsePackwerk::PackageSet
+  class << self
+    sig do
+      params(
+        package_pathspec: T::Array[::String],
+        exclude_pathspec: T::Array[::String]
+      ).returns(T::Array[::ParsePackwerk::Package])
+    end
+    def from(package_pathspec:, exclude_pathspec:); end
+
+    private
+
+    sig { params(globs: T::Array[::String], path: ::Pathname).returns(T::Boolean) }
+    def exclude_path?(globs, path); end
+  end
+end
+
 ParsePackwerk::ROOT_PACKAGE_NAME = T.let(T.unsafe(nil), String)
 
 class ParsePackwerk::Violation < ::T::Struct

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: code_ownership
 version: !ruby/object:Gem::Version
-  version: 1.28.0
+  version: 1.29.0
 platform: ruby
 authors:
 - Gusto Engineers
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-06-14 00:00:00.000000000 Z
+date: 2022-11-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: code_teams
@@ -150,7 +150,7 @@ files:
 - lib/code_ownership/private/validations/interface.rb
 - sorbet/config
 - sorbet/rbi/gems/code_teams@1.0.0.rbi
-- sorbet/rbi/gems/parse_packwerk@0.7.0.rbi
+- sorbet/rbi/gems/parse_packwerk@0.12.0.rbi
 - sorbet/rbi/manual.rbi
 - sorbet/rbi/todo.rbi
 homepage: https://github.com/rubyatscale/code_ownership
@@ -176,7 +176,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.7
+rubygems_version: 3.1.6
 signing_key: 
 specification_version: 4
 summary: A gem to help engineering teams declare ownership of code