code_ownership 1.23.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c664c64c94e083083f3187002fc77ffb7d40cbc7c5c76ae0291b9d5c11cd224f
+  data.tar.gz: cf6dcc613f67a6e7723fa73a079dabfa8782ddba886441afd8e5608eaa9249ec
+SHA512:
+  metadata.gz: 54373f777f534bd2f600510e1ee94b85151bc5016d076d35ef5ed7d140a1d8b53d1bcea24a1af2badebc5939c52c1e2660e066eb49fcbcc4fb7a330cf227664f
+  data.tar.gz: c94fd3d689b09a27b8db89b339e3037ec8e6c1fe76413226b22662ce068599ecd30a6aa80e0f90e389a0d1a17bb58afebd650ed4c8bd57523336bd688517f819

data/README.md

@@ -0,0 +1,101 @@
+# CodeOwnership
+This gem helps engineering teams declare ownership of code.
+
+Check out `lib/code_ownership.rb` to see the public API.
+
+Check out `code_ownership_spec.rb` to see examples of how code ownership is used.
+
+## 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
+enforce_dependency: true
+enforce_privacy: true
+metadata:
+  owner: Team
+```
+
+### Glob-Based Ownership
+In your team's configured YML (see [`bigrails-teams`](https://github.com/bigrails/bigrails-teams)), you can set `owned_globs` to be a glob of files your team owns. For example, in `my_team.yml`:
+```yml
+name: My Team
+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
+```
+## Usage: Reading CodeOwnership
+### `for_file`
+`CodeOwnership.for_file`, given a relative path to a file returns a `Teams::Team` if there is a team that owns the file, `nil` otherwise.
+
+```ruby
+CodeOwnership.for_file('path/to/file/relative/to/application/root.rb')
+```
+
+Contributor note: If you are making updates to this method or the methods getting used here, please benchmark the performance of the new implementation against the current for both `for_files` and `for_file` (with 1, 100, 1000 files).
+
+See `code_ownership_spec.rb` for examples.
+
+### `for_backtrace`
+`CodeOwnership.for_backtrace` can be given a backtrace and will either return `nil`, or a `Teams::Team`.
+
+```ruby
+CodeOwnership.for_backtrace(exception.backtrace)
+```
+
+This will go through the backtrace, and return the first found owner of the files associated with frames within the backtrace.
+
+See `code_ownership_spec.rb` for an example.
+
+### `for_class`
+
+`CodeOwnership.for_class` can be given a class and will either return `nil`, or a `Teams::Team`.
+
+```ruby
+CodeOwnership.for_class(MyClass.name)
+```
+
+Under the hood, this finds the file where the class is defined and returns the owner of that file.
+
+See `code_ownership_spec.rb` for an example.
+
+## 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 `Teams.all`).
+3) All files have ownership. You can specify in `unowned_globs` to represent a TODO list of files to add ownership to.
+3) The `.github/CODEOWNERS` file is up to date. This is automatically corrected and staged unless specified otherwise with `bin/codeownership validate --skip-autocorrect --skip-stage`. You can turn this validation off by setting `skip_codeowners_validation: true` in `code_ownership.yml`.
+
+CodeOwnership also allows you to specify which globs and file extensions should be considered ownable.
+
+Here is an example `config/code_ownership.yml`.
+```yml
+owned_globs:
+  - '{app,components,config,frontend,lib,packs,spec}/**/*.{rb,rake,js,jsx,ts,tsx}'
+unowned_globs:
+  - db/**/*
+  - app/services/some_file1.rb
+  - app/services/some_file2.rb
+  - frontend/javascripts/**/__generated__/**/*
+```
+You can call the validation function with the Ruby API 
+```ruby
+CodeOwnership.validate!
+```
+or the CLI
+```
+bin/codeownership validate
+```
+
+## Development
+
+Please add to `CHANGELOG.md` and this `README.md` when you make make changes.

data/bin/codeownership

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+# typed: strict
+
+require 'code_ownership'
+CodeOwnership::Cli.run!(ARGV)

data/lib/code_ownership/cli.rb

@@ -0,0 +1,60 @@
+# typed: true
+
+require 'optparse'
+require 'pathname'
+
+module CodeOwnership
+  class Cli
+    def self.run!(argv)
+      # Someday we might support other subcommands. When we do that, we can call
+      # argv.shift to get the first argument and check if it's a given subcommand.
+      command = argv.shift
+      if command == 'validate'
+        validate!(argv)
+      end
+    end
+
+    def self.validate!(argv)
+      options = {}
+
+      parser = OptionParser.new do |opts|
+        opts.banner = 'Usage: bin/codeownership validate [options]'
+
+        opts.on('--skip-autocorrect', 'Skip automatically correcting any errors, such as the .github/CODEOWNERS file') do
+          options[:skip_autocorrect] = true
+        end
+
+        opts.on('-d', '--diff', 'Only run validations with staged files') do
+          options[:diff] = true
+        end
+
+        opts.on('-s', '--skip-stage', 'Skips staging the CODEOWNERS file') do
+          options[:skip_stage] = true
+        end
+
+        opts.on('--help', 'Shows this prompt') do
+          puts opts
+          exit
+        end
+      end
+      args = parser.order!(argv) {}
+      parser.parse!(args)
+
+      files = if options[:diff]
+        ENV.fetch('CODEOWNERS_GIT_STAGED_FILES') { `git diff --staged --name-only` }.split("\n").select do |file|
+          File.exist?(file)
+        end
+      else
+        Private.tracked_files
+      end
+
+      CodeOwnership.validate!(
+        files: files,
+        autocorrect: !options[:skip_autocorrect],
+        stage_changes: !options[:skip_stage]
+      )
+    end
+
+    private_class_method :validate!
+  end
+end

data/lib/code_ownership/private/configuration.rb

@@ -0,0 +1,37 @@
+# typed: strict
+
+module CodeOwnership
+  module Private
+    class Configuration < T::Struct
+      extend T::Sig
+      DEFAULT_JS_PACKAGE_PATHS = T.let(['**/'], T::Array[String])
+
+      const :owned_globs, T::Array[String]
+      const :unowned_globs, T::Array[String]
+      const :js_package_paths, T::Array[String]
+      const :skip_codeowners_validation, T::Boolean
+
+      sig { returns(Configuration) }
+      def self.fetch
+        config_hash = YAML.load_file('config/code_ownership.yml')
+
+        new(
+          owned_globs: config_hash.fetch('owned_globs', []),
+          unowned_globs: config_hash.fetch('unowned_globs', []),
+          js_package_paths: js_package_paths(config_hash),
+          skip_codeowners_validation: config_hash.fetch('skip_codeowners_validation', false)
+        )
+      end
+
+      sig { params(config_hash: T::Hash[T.untyped, T.untyped]).returns(T::Array[String]) }
+      def self.js_package_paths(config_hash)
+        specified_package_paths = config_hash['js_package_paths']
+        if specified_package_paths.nil?
+          DEFAULT_JS_PACKAGE_PATHS.dup
+        else
+          Array(specified_package_paths)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+# typed: strict
+
+module CodeOwnership
+  module Private
+    module OwnershipMappers
+      # Calculate, cache, and return a mapping of file names (relative to the root
+      # of the repository) to team name.
+      #
+      # Example:
+      #
+      #   {
+      #     'app/models/company.rb' => Team.find('Setup & Onboarding'),
+      #     ...
+      #   }
+      class FileAnnotations
+        extend T::Sig
+        include Interface
+
+        @@map_files_to_owners = T.let({}, T.nilable(T::Hash[String, T.nilable(::Teams::Team)])) # rubocop:disable Style/ClassVars
+
+        TEAM_PATTERN = T.let(/\A(?:#|\/\/) @team (?<team>.*)\Z/.freeze, Regexp)
+
+        sig do
+          override.params(file: String).
+            returns(T.nilable(::Teams::Team))
+        end
+        def map_file_to_owner(file)
+          file_annotation_based_owner(file)
+        end
+
+        sig do
+          override.
+            params(files: T::Array[String]).
+            returns(T::Hash[String, T.nilable(::Teams::Team)])
+        end
+        def map_files_to_owners(files)
+          return @@map_files_to_owners if @@map_files_to_owners&.keys && @@map_files_to_owners.keys.count > 0
+
+          @@map_files_to_owners = files.each_with_object({}) do |filename_relative_to_root, mapping| # rubocop:disable Style/ClassVars
+            owner = file_annotation_based_owner(filename_relative_to_root)
+            next unless owner
+
+            mapping[filename_relative_to_root] = owner
+          end
+        end
+
+        sig { params(filename: String).returns(T.nilable(Teams::Team)) }
+        def file_annotation_based_owner(filename)
+          # If for a directory is named with an ownable extension, we need to skip
+          # so File.foreach doesn't blow up below. This was needed because Cypress
+          # screenshots are saved to a folder with the test suite filename.
+          return if File.directory?(filename)
+          return unless File.file?(filename)
+
+          # The annotation should be on line 1 but as of this comment
+          # there's no linter installed to enforce that. We therefore check the
+          # first line (the Ruby VM makes a single `read(1)` call for 8KB),
+          # and if the annotation isn't in the first two lines we assume it
+          # doesn't exist.
+
+          line_1 = File.foreach(filename).first
+
+          return if !line_1
+
+          begin
+            team = line_1[TEAM_PATTERN, :team]
+          rescue ArgumentError => ex
+            if ex.message.include?('invalid byte sequence')
+              team = nil
+            else
+              raise
+            end
+          end
+
+          return unless team
+
+          Private.find_team!(
+            team,
+            filename
+          )
+        end
+
+        sig { params(filename: String).void }
+        def remove_file_annotation!(filename)
+          if file_annotation_based_owner(filename)
+            filepath = Pathname.new(filename)
+            lines = filepath.read.split("\n")
+            new_lines = lines.select { |line| !line[TEAM_PATTERN] }
+            # We explicitly add a final new line since splitting by new line when reading the file lines
+            # ignores new lines at the ends of files
+            # We also remove leading new lines, since there is after a new line after an annotation
+            new_file_contents = "#{new_lines.join("\n")}\n".gsub(/\A\n+/, '')
+            filepath.write(new_file_contents)
+          end
+        end
+
+        sig do
+          override.returns(T::Hash[String, T.nilable(::Teams::Team)])
+        end
+        def codeowners_lines_to_owners
+          @@map_files_to_owners = nil # rubocop:disable Style/ClassVars
+          map_files_to_owners(Private.tracked_files)
+        end
+
+        sig { override.returns(String) }
+        def description
+          'Annotations at the top of file'
+        end
+
+        sig { override.void }
+        def bust_caches!
+          @@map_files_to_owners = {} # rubocop:disable Style/ClassVars
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+# typed: strict
+
+module CodeOwnership
+  module Private
+    module OwnershipMappers
+      module Interface
+        extend T::Sig
+        extend T::Helpers
+
+        interface!
+
+        #
+        # This should be fast when run with ONE file
+        #
+        sig do
+          abstract.params(file: String).
+            returns(T.nilable(::Teams::Team))
+        end
+        def map_file_to_owner(file)
+        end
+
+        #
+        # This should be fast when run with MANY files
+        #
+        sig do
+          abstract.params(files: T::Array[String]).
+            returns(T::Hash[String, T.nilable(::Teams::Team)])
+        end
+        def map_files_to_owners(files)
+        end
+
+        sig do
+          abstract.returns(T::Hash[String, T.nilable(::Teams::Team)])
+        end
+        def codeowners_lines_to_owners
+        end
+
+        sig { abstract.returns(String) }
+        def description
+        end
+
+        sig { abstract.void }
+        def bust_caches!
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+# typed: true
+
+module CodeOwnership
+  module Private
+    module OwnershipMappers
+      class JsPackageOwnership
+        extend T::Sig
+        include Interface
+
+        @@package_json_cache = T.let({}, T::Hash[String, T.nilable(ParseJsPackages::Package)]) # rubocop:disable Style/ClassVars
+
+        sig do
+          override.params(file: String).
+            returns(T.nilable(::Teams::Team))
+        end
+        def map_file_to_owner(file)
+          package = map_file_to_relevant_package(file)
+
+          return nil if package.nil?
+
+          owner_for_package(package)
+        end
+
+        sig do
+          override.
+            params(files: T::Array[String]).
+            returns(T::Hash[String, T.nilable(::Teams::Team)])
+        end
+        def map_files_to_owners(files) # rubocop:disable Lint/UnusedMethodArgument
+          ParseJsPackages.all.each_with_object({}) do |package, res|
+            owner = owner_for_package(package)
+            next if owner.nil?
+
+            glob = package.directory.join('**/**').to_s
+            Dir.glob(glob).each do |path|
+              res[path] = owner
+            end
+          end
+        end
+
+        #
+        # Package ownership ignores the passed in files when generating code owners lines.
+        # This is because Package ownership knows that the fastest way to find code owners for package based ownership
+        # is to simply iterate over the packages and grab the owner, rather than iterating over each file just to get what package 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.returns(T::Hash[String, T.nilable(::Teams::Team)])
+        end
+        def codeowners_lines_to_owners
+          ParseJsPackages.all.each_with_object({}) do |package, res|
+            owner = owner_for_package(package)
+            next if owner.nil?
+
+            res[package.directory.join('**/**').to_s] = owner
+          end
+        end
+
+        sig { override.returns(String) }
+        def description
+          'Owner metadata key in package.json'
+        end
+
+        sig { params(package: ParseJsPackages::Package).returns(T.nilable(Teams::Team)) }
+        def owner_for_package(package)
+          raw_owner_value = package.metadata['owner']
+          return nil if !raw_owner_value
+
+          Private.find_team!(
+            raw_owner_value,
+            package.name
+          )
+        end
+
+        sig { override.void }
+        def bust_caches!
+          @@package_json_cache = {} # rubocop:disable Style/ClassVars
+        end
+
+        private
+
+        # takes a file and finds the relevant `package.json` file by walking up the directory
+        # structure. Example, given `packages/a/b/c.rb`, this looks for `packages/a/b/package.json`, `packages/a/package.json`,
+        # `packages/package.json`, and `package.json` 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(ParseJsPackages::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_json_path = potential_relative_path_name.
+              join(ParseJsPackages::PACKAGE_JSON_NAME)
+
+            potential_package_json_string = potential_package_json_path.to_s
+
+            package = nil
+            if @@package_json_cache.key?(potential_package_json_string)
+              package = @@package_json_cache[potential_package_json_string]
+            elsif potential_package_json_path.exist?
+              package = ParseJsPackages::Package.from(potential_package_json_path)
+
+              @@package_json_cache[potential_package_json_string] = package
+            else
+              @@package_json_cache[potential_package_json_string] = nil
+            end
+
+            return package unless package.nil?
+          end
+
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+# typed: true
+
+module CodeOwnership
+  module Private
+    module OwnershipMappers
+      class PackageOwnership
+        extend T::Sig
+        include Interface
+
+        @@package_yml_cache = T.let({}, T::Hash[String, T.nilable(ParsePackwerk::Package)]) # rubocop:disable Style/ClassVars
+
+        sig do
+          override.params(file: String).
+            returns(T.nilable(::Teams::Team))
+        end
+        def map_file_to_owner(file)
+          package = map_file_to_relevant_package(file)
+
+          return nil if package.nil?
+
+          owner_for_package(package)
+        end
+
+        sig do
+          override.
+            params(files: T::Array[String]).
+            returns(T::Hash[String, T.nilable(::Teams::Team)])
+        end
+        def map_files_to_owners(files) # rubocop:disable Lint/UnusedMethodArgument
+          ParsePackwerk.all.each_with_object({}) do |package, res|
+            owner = owner_for_package(package)
+            next if owner.nil?
+
+            glob = package.directory.join('**/**').to_s
+            Dir.glob(glob).each do |path|
+              res[path] = owner
+            end
+          end
+        end
+
+        #
+        # Package ownership ignores the passed in files when generating code owners lines.
+        # This is because Package ownership knows that the fastest way to find code owners for package based ownership
+        # is to simply iterate over the packages and grab the owner, rather than iterating over each file just to get what package 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.returns(T::Hash[String, T.nilable(::Teams::Team)])
+        end
+        def codeowners_lines_to_owners
+          ParsePackwerk.all.each_with_object({}) do |package, res|
+            owner = owner_for_package(package)
+            next if owner.nil?
+
+            res[package.directory.join('**/**').to_s] = owner
+          end
+        end
+
+        sig { override.returns(String) }
+        def description
+          'Owner metadata key in package.yml'
+        end
+
+        sig { params(package: ParsePackwerk::Package).returns(T.nilable(Teams::Team)) }
+        def owner_for_package(package)
+          raw_owner_value = package.metadata['owner']
+          return nil if !raw_owner_value
+
+          Private.find_team!(
+            raw_owner_value,
+            package.yml.to_s
+          )
+        end
+
+        sig { override.void }
+        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
+end

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

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+# typed: true
+
+module CodeOwnership
+  module Private
+    module OwnershipMappers
+      class TeamGlobs
+        extend T::Sig
+        include Interface
+
+        @@map_files_to_owners = T.let(@map_files_to_owners, T.nilable(T::Hash[String, T.nilable(::Teams::Team)])) # rubocop:disable Style/ClassVars
+        @@map_files_to_owners = {} # rubocop:disable Style/ClassVars
+        @@codeowners_lines_to_owners = T.let(@codeowners_lines_to_owners, T.nilable(T::Hash[String, T.nilable(::Teams::Team)])) # rubocop:disable Style/ClassVars
+        @@codeowners_lines_to_owners = {} # rubocop:disable Style/ClassVars
+
+        sig do
+          override.
+            params(files: T::Array[String]).
+            returns(T::Hash[String, T.nilable(::Teams::Team)])
+        end
+        def map_files_to_owners(files) # rubocop:disable Lint/UnusedMethodArgument
+          return @@map_files_to_owners if @@map_files_to_owners&.keys && @@map_files_to_owners.keys.count > 0
+
+          @@map_files_to_owners = Teams.all.each_with_object({}) do |team, map| # rubocop:disable Style/ClassVars
+            TeamPlugins::Ownership.for(team).owned_globs.each do |glob|
+              Dir.glob(glob).each do |filename|
+                map[filename] = team
+              end
+            end
+          end
+        end
+
+        sig do
+          override.params(file: String).
+            returns(T.nilable(::Teams::Team))
+        end
+        def map_file_to_owner(file)
+          map_files_to_owners([file])[file]
+        end
+
+        sig do
+          override.returns(T::Hash[String, T.nilable(::Teams::Team)])
+        end
+        def codeowners_lines_to_owners
+          return @@codeowners_lines_to_owners if @@codeowners_lines_to_owners&.keys && @@codeowners_lines_to_owners.keys.count > 0
+
+          @@codeowners_lines_to_owners = Teams.all.each_with_object({}) do |team, map| # rubocop:disable Style/ClassVars
+            TeamPlugins::Ownership.for(team).owned_globs.each do |owned_glob|
+              map[owned_glob] = team
+            end
+          end
+        end
+
+        sig { override.void }
+        def bust_caches!
+          @@codeowners_lines_to_owners = {} # rubocop:disable Style/ClassVars
+          @@map_files_to_owners = {} # rubocop:disable Style/ClassVars
+        end
+
+        sig { override.returns(String) }
+        def description
+          'Team-specific owned globs'
+        end
+      end
+    end
+  end
+end