code_ownership 1.23.0

data/lib/code_ownership/private/parse_js_packages.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+# typed: true
+
+module CodeOwnership
+  module Private
+    # Modeled off of ParsePackwerk
+    module ParseJsPackages
+      extend T::Sig
+
+      ROOT_PACKAGE_NAME = 'root'
+      PACKAGE_JSON_NAME = T.let('package.json', String)
+      METADATA = 'metadata'
+
+      class Package < T::Struct
+        extend T::Sig
+
+        const :name, String
+        const :metadata, T::Hash[String, T.untyped]
+
+        sig { params(pathname: Pathname).returns(Package) }
+        def self.from(pathname)
+          package_loaded_json = JSON.parse(pathname.read)
+
+          package_name = if pathname.dirname == Pathname.new('.')
+            ROOT_PACKAGE_NAME
+          else
+            pathname.dirname.cleanpath.to_s
+          end
+
+          new(
+            name: package_name,
+            metadata: package_loaded_json[METADATA] || {}
+          )
+        end
+
+        sig { returns(Pathname) }
+        def directory
+          root_pathname = Pathname.new('.')
+          name == ROOT_PACKAGE_NAME ? root_pathname.cleanpath : root_pathname.join(name).cleanpath
+        end
+      end
+
+      sig do
+        returns(T::Array[Package])
+      end
+      def self.all
+        package_glob_patterns = Private.configuration.js_package_paths.map do |pathspec|
+          File.join(pathspec, PACKAGE_JSON_NAME)
+        end
+
+        # The T.unsafe is because the upstream RBI is wrong for Pathname.glob
+        T.unsafe(Pathname).glob(package_glob_patterns).map(&:cleanpath).map do |path|
+          Package.from(path)
+        end
+      end
+    end
+  end
+end

data/lib/code_ownership/private/team_plugins/github.rb

@@ -0,0 +1,24 @@
+# typed: true
+
+module CodeOwnership
+  module Private
+    module TeamPlugins
+      class Github < Teams::Plugin
+        extend T::Sig
+        extend T::Helpers
+
+        GithubStruct = Struct.new(:team, :do_not_add_to_codeowners_file)
+
+        sig { returns(GithubStruct) }
+        def github
+          raw_github = @team.raw_hash['github'] || {}
+
+          GithubStruct.new(
+            raw_github['team'],
+            raw_github['do_not_add_to_codeowners_file'] || false
+          )
+        end
+      end
+    end
+  end
+end

data/lib/code_ownership/private/team_plugins/ownership.rb

@@ -0,0 +1,17 @@
+# typed: true
+
+module CodeOwnership
+  module Private
+    module TeamPlugins
+      class Ownership < Teams::Plugin
+        extend T::Sig
+        extend T::Helpers
+
+        sig { returns(T::Array[String]) }
+        def owned_globs
+          @team.raw_hash['owned_globs'] || []
+        end
+      end
+    end
+  end
+end

data/lib/code_ownership/private/validations/files_have_owners.rb

@@ -0,0 +1,34 @@
+# typed: strict
+
+module CodeOwnership
+  module Private
+    module Validations
+      class FilesHaveOwners
+        extend T::Sig
+        extend T::Helpers
+        include Interface
+
+        sig { override.params(files: T::Array[String], autocorrect: T::Boolean, stage_changes: T::Boolean).returns(T::Array[String]) }
+        def validation_errors(files:, autocorrect: true, stage_changes: true)
+          allow_list = Dir.glob(Private.configuration.unowned_globs)
+          files_by_mapper = Private.files_by_mapper(files)
+          files_not_mapped_at_all = files_by_mapper.select { |_file, mapper_descriptions| mapper_descriptions.count == 0 }.keys
+
+          files_without_owners = files_not_mapped_at_all - allow_list
+
+          errors = T.let([], T::Array[String])
+
+          if files_without_owners.any?
+            errors << <<~MSG
+              Some files are missing ownership:
+
+              #{files_without_owners.map { |file| "- #{file}" }.join("\n")}
+            MSG
+          end
+
+          errors
+        end
+      end
+    end
+  end
+end

data/lib/code_ownership/private/validations/files_have_unique_owners.rb

@@ -0,0 +1,32 @@
+# typed: strict
+
+module CodeOwnership
+  module Private
+    module Validations
+      class FilesHaveUniqueOwners
+        extend T::Sig
+        extend T::Helpers
+        include Interface
+
+        sig { override.params(files: T::Array[String], autocorrect: T::Boolean, stage_changes: T::Boolean).returns(T::Array[String]) }
+        def validation_errors(files:, autocorrect: true, stage_changes: true)
+          files_by_mapper = Private.files_by_mapper(files)
+
+          files_mapped_by_multiple_mappers = files_by_mapper.select { |_file, mapper_descriptions| mapper_descriptions.count > 1 }.to_h
+
+          errors = T.let([], T::Array[String])
+
+          if files_mapped_by_multiple_mappers.any?
+            errors << <<~MSG
+              Code ownership should only be defined for each file in one way. The following files have declared ownership in multiple ways.
+
+              #{files_mapped_by_multiple_mappers.map { |file, descriptions| "- #{file} (#{descriptions.join(', ')})" }.join("\n")}
+            MSG
+          end
+
+          errors
+        end
+      end
+    end
+  end
+end

data/lib/code_ownership/private/validations/github_codeowners_up_to_date.rb

@@ -0,0 +1,85 @@
+# typed: strict
+
+module CodeOwnership
+  module Private
+    module Validations
+      class GithubCodeownersUpToDate
+        extend T::Sig
+        extend T::Helpers
+        include Interface
+
+        sig { override.params(files: T::Array[String], autocorrect: T::Boolean, stage_changes: T::Boolean).returns(T::Array[String]) }
+        def validation_errors(files:, autocorrect: true, stage_changes: true)
+          return [] if Private.configuration.skip_codeowners_validation
+
+          codeowners_filepath = Pathname.pwd.join('.github/CODEOWNERS')
+          FileUtils.mkdir_p(codeowners_filepath.dirname) if !codeowners_filepath.dirname.exist?
+
+          header = <<~HEADER
+            # STOP! - DO NOT EDIT THIS FILE MANUALLY
+            # This file was automatically generated by "bin/codeownership validate".
+            #
+            # CODEOWNERS is used for GitHub to suggest code/file owners to various GitHub
+            # teams. This is useful when developers create Pull Requests since the
+            # code/file owner is notified. Reference GitHub docs for more details:
+            # https://help.github.com/en/articles/about-code-owners
+          HEADER
+
+          contents = [
+            header,
+            *codeowners_file_lines,
+            nil, # For end-of-file newline
+          ].join("\n")
+
+          codeowners_up_to_date = codeowners_filepath.exist? && codeowners_filepath.read == contents
+
+          errors = T.let([], T::Array[String])
+
+          if !codeowners_up_to_date
+            if autocorrect
+              codeowners_filepath.write(contents)
+              if stage_changes
+                `git add #{codeowners_filepath}`
+              end
+            else
+              errors << "CODEOWNERS out of date. Ensure pre-commit hook is set up correctly and used. You can also run bin/codeownership validate to update the CODEOWNERS file\n"
+            end
+          end
+
+          errors
+        end
+
+        private
+
+        # Generate the contents of a CODEOWNERS file that GitHub can use to
+        # automatically assign reviewers
+        # https://help.github.com/articles/about-codeowners/
+        sig { returns(T::Array[String]) }
+        def codeowners_file_lines
+          github_team_map = Teams.all.each_with_object({}) do |team, map|
+            team_github = TeamPlugins::Github.for(team).github
+            next if team_github.do_not_add_to_codeowners_file
+
+            map[team.name] = team_github.team
+          end
+
+          Private.mappers.flat_map do |mapper|
+            codeowners_lines = mapper.codeowners_lines_to_owners.filter_map do |line, team|
+              team_mapping = github_team_map[team&.name]
+              next unless team_mapping
+
+              "/#{line} #{team_mapping}"
+            end
+            next [] if codeowners_lines.empty?
+
+            [
+              '',
+              "# #{mapper.description}",
+              *codeowners_lines.sort,
+            ]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,18 @@
+# typed: strict
+
+module CodeOwnership
+  module Private
+    module Validations
+      module Interface
+        extend T::Sig
+        extend T::Helpers
+
+        interface!
+
+        sig { abstract.params(files: T::Array[String], autocorrect: T::Boolean, stage_changes: T::Boolean).returns(T::Array[String]) }
+        def validation_errors(files:, autocorrect: true, stage_changes: true)
+        end
+      end
+    end
+  end
+end

data/lib/code_ownership/private.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+# typed: strict
+
+require 'code_ownership/private/configuration'
+require 'code_ownership/private/team_plugins/ownership'
+require 'code_ownership/private/team_plugins/github'
+require 'code_ownership/private/parse_js_packages'
+require 'code_ownership/private/validations/interface'
+require 'code_ownership/private/validations/files_have_owners'
+require 'code_ownership/private/validations/github_codeowners_up_to_date'
+require 'code_ownership/private/validations/files_have_unique_owners'
+require 'code_ownership/private/ownership_mappers/interface'
+require 'code_ownership/private/ownership_mappers/file_annotations'
+require 'code_ownership/private/ownership_mappers/team_globs'
+require 'code_ownership/private/ownership_mappers/package_ownership'
+require 'code_ownership/private/ownership_mappers/js_package_ownership'
+
+module CodeOwnership
+  module Private
+    extend T::Sig
+
+    sig { returns(Private::Configuration) }
+    def self.configuration
+      @configuration ||= T.let(@configuration, T.nilable(Private::Configuration))
+      @configuration ||= Private::Configuration.fetch
+    end
+
+    sig { void }
+    def self.bust_caches!
+      @configuration = nil
+      @tracked_files = nil
+      @files_by_mapper = nil
+    end
+
+    sig { params(files: T::Array[String], autocorrect: T::Boolean, stage_changes: T::Boolean).void }
+    def self.validate!(files:, autocorrect: true, stage_changes: true)
+      validators = [
+        Validations::FilesHaveOwners.new,
+        Validations::FilesHaveUniqueOwners.new,
+        Validations::GithubCodeownersUpToDate.new,
+      ]
+
+      errors = validators.flat_map do |validator|
+        validator.validation_errors(
+          files: files,
+          autocorrect: autocorrect,
+          stage_changes: stage_changes
+        )
+      end
+
+      if errors.any?
+        errors << 'See https://github.com/bigrails/code_ownership/README.md for more details'
+        raise InvalidCodeOwnershipConfigurationError.new(errors.join("\n")) # rubocop:disable Style/RaiseArgs
+      end
+    end
+
+    sig { returns(T::Array[Private::OwnershipMappers::Interface]) }
+    def self.mappers
+      [
+        file_annotations_mapper,
+        Private::OwnershipMappers::TeamGlobs.new,
+        Private::OwnershipMappers::PackageOwnership.new,
+        Private::OwnershipMappers::JsPackageOwnership.new,
+      ]
+    end
+
+    sig { returns(Private::OwnershipMappers::FileAnnotations) }
+    def self.file_annotations_mapper
+      @file_annotations_mapper = T.let(@file_annotations_mapper, T.nilable(Private::OwnershipMappers::FileAnnotations))
+      @file_annotations_mapper ||= Private::OwnershipMappers::FileAnnotations.new
+    end
+
+    # Returns a string version of the relative path to a Rails constant,
+    # or nil if it can't find something
+    sig { params(klass: T.nilable(T.any(Class, Module))).returns(T.nilable(String)) }
+    def self.path_from_klass(klass)
+      if klass
+        path = Object.const_source_location(klass.to_s)&.first
+        (path && Pathname.new(path).relative_path_from(Pathname.pwd).to_s) || nil
+      else
+        nil
+      end
+    end
+
+    #
+    # The output of this function is string pathnames relative to the root.
+    #
+    sig { returns(T::Array[String]) }
+    def self.tracked_files
+      @tracked_files ||= T.let(@tracked_files, T.nilable(T::Array[String]))
+      @tracked_files ||= Dir.glob(configuration.owned_globs)
+    end
+
+    sig { params(team_name: String, location_of_reference: String).returns(Teams::Team) }
+    def self.find_team!(team_name, location_of_reference)
+      found_team = Teams.find(team_name)
+      if found_team.nil?
+        raise StandardError, "Could not find team with name: `#{team_name}` in #{location_of_reference}. Make sure the team is one of `#{Teams.all.map(&:name).sort}`"
+      else
+        found_team
+      end
+    end
+
+    sig { params(files: T::Array[String]).returns(T::Hash[String, T::Array[String]]) }
+    def self.files_by_mapper(files)
+      @files_by_mapper ||= T.let(@files_by_mapper, T.nilable(T::Hash[String, T::Array[String]]))
+      @files_by_mapper ||= begin
+        files_by_mapper = files.map { |file| [file, []] }.to_h
+
+        Private.mappers.each do |mapper|
+          mapper.map_files_to_owners(files).each do |file, _team|
+            files_by_mapper[file] ||= []
+            T.must(files_by_mapper[file]) << mapper.description
+          end
+        end
+
+        files_by_mapper
+      end
+    end
+  end
+
+  private_constant :Private
+end

data/lib/code_ownership.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+# typed: strict
+
+require 'set'
+require 'teams'
+require 'sorbet-runtime'
+require 'json'
+require 'parse_packwerk'
+require 'code_ownership/cli'
+require 'code_ownership/private'
+
+module CodeOwnership
+  extend self
+  extend T::Sig
+  extend T::Helpers
+
+  requires_ancestor { Kernel }
+
+  sig { params(file: String).returns(T.nilable(Teams::Team)) }
+  def for_file(file)
+    @for_file ||= T.let(@for_file, T.nilable(T::Hash[String, T.nilable(Teams::Team)]))
+    @for_file ||= {}
+
+    return nil if file.start_with?('./')
+    return @for_file[file] if @for_file.key?(file)
+
+    owner = T.let(nil, T.nilable(Teams::Team))
+
+    Private.mappers.each do |mapper|
+      owner = mapper.map_file_to_owner(file)
+      break if owner
+    end
+
+    @for_file[file] = owner
+  end
+
+  class InvalidCodeOwnershipConfigurationError < StandardError
+  end
+
+  sig { params(filename: String).void }
+  def self.remove_file_annotation!(filename)
+    Private.file_annotations_mapper.remove_file_annotation!(filename)
+  end
+
+  sig do
+    params(
+      files: T::Array[String],
+      autocorrect: T::Boolean,
+      stage_changes: T::Boolean
+    ).void
+  end
+  def validate!(
+    files: Private.tracked_files,
+    autocorrect: true,
+    stage_changes: true
+  )
+    tracked_file_subset = Private.tracked_files & files
+    Private.validate!(files: tracked_file_subset, autocorrect: autocorrect, stage_changes: stage_changes)
+  end
+
+  # Given a backtrace from either `Exception#backtrace` or `caller`, find the
+  # first line that corresponds to a file with assigned ownership
+  sig { params(backtrace: T.nilable(T::Array[String]), excluded_teams: T::Array[::Teams::Team]).returns(T.nilable(::Teams::Team)) }
+  def for_backtrace(backtrace, excluded_teams: [])
+    return unless backtrace
+
+    # The pattern for a backtrace hasn't changed in forever and is considered
+    # stable: https://github.com/ruby/ruby/blob/trunk/vm_backtrace.c#L303-L317
+    #
+    # This pattern matches a line like the following:
+    #
+    #   ./app/controllers/some_controller.rb:43:in `block (3 levels) in create'
+    #
+    backtrace_line = %r{\A(#{Pathname.pwd}/|\./)?
+        (?<file>.+)       # Matches 'app/controllers/some_controller.rb'
+        :
+        (?<line>\d+)      # Matches '43'
+        :in\s
+        `(?<function>.*)' # Matches "`block (3 levels) in create'"
+      \z}x
+
+    backtrace.each do |line|
+      match = line.match(backtrace_line)
+
+      if match
+        team = CodeOwnership.for_file(T.must(match[:file]))
+        if team && !excluded_teams.include?(team)
+          return team
+        end
+      end
+    end
+    nil
+  end
+
+  sig { params(klass: T.nilable(T.any(Class, Module))).returns(T.nilable(::Teams::Team)) }
+  def for_class(klass)
+    @memoized_values ||= T.let(@memoized_values, T.nilable(T::Hash[String, T.nilable(::Teams::Team)]))
+    @memoized_values ||= {}
+    # We use key because the memoized value could be `nil`
+    if !@memoized_values.key?(klass.to_s)
+      path = Private.path_from_klass(klass)
+      return nil if path.nil?
+
+      value_to_memoize = for_file(path)
+      @memoized_values[klass.to_s] = value_to_memoize
+      value_to_memoize
+    else
+      @memoized_values[klass.to_s]
+    end
+  end
+
+  sig { params(package: ParsePackwerk::Package).returns(T.nilable(::Teams::Team)) }
+  def for_package(package)
+    Private::OwnershipMappers::PackageOwnership.new.owner_for_package(package)
+  end
+
+  # Generally, you should not ever need to do this, because once your ruby process loads, cached content should not change.
+  # Namely, the set of files, packages, and directories which are tracked for ownership should not change.
+  # The primary reason this is helpful is for clients of CodeOwnership who want to test their code, and each test context
+  # has different ownership and tracked files.
+  sig { void }
+  def self.bust_caches!
+    @for_file = nil
+    @memoized_values = nil
+    Private.bust_caches!
+    Private.mappers.each(&:bust_caches!)
+  end
+end

data/sorbet/config

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

data/sorbet/rbi/gems/bigrails-teams@0.1.0.rbi

@@ -0,0 +1,120 @@
+# typed: true
+
+# DO NOT EDIT MANUALLY
+# This is an autogenerated file for types exported from the `bigrails-teams` gem.
+# Please instead update this file by running `bin/tapioca gem bigrails-teams`.
+
+module Teams
+  class << self
+    sig { returns(T::Array[::Teams::Team]) }
+    def all; end
+
+    sig { void }
+    def bust_caches!; end
+
+    sig { params(name: ::String).returns(T.nilable(::Teams::Team)) }
+    def find(name); end
+
+    sig { params(dir: ::String).returns(T::Array[::Teams::Team]) }
+    def for_directory(dir); end
+
+    sig { params(string: ::String).returns(::String) }
+    def tag_value_for(string); end
+
+    sig { params(teams: T::Array[::Teams::Team]).returns(T::Array[::String]) }
+    def validation_errors(teams); end
+  end
+end
+
+class Teams::IncorrectPublicApiUsageError < ::StandardError; end
+
+class Teams::Plugin
+  abstract!
+
+  sig { params(team: ::Teams::Team).void }
+  def initialize(team); end
+
+  class << self
+    sig { returns(T::Array[T.class_of(Teams::Plugin)]) }
+    def all_plugins; end
+
+    sig { params(team: ::Teams::Team).returns(T.attached_class) }
+    def for(team); end
+
+    sig { params(base: T.untyped).void }
+    def inherited(base); end
+
+    sig { params(team: ::Teams::Team, key: ::String).returns(::String) }
+    def missing_key_error_message(team, key); end
+
+    sig { params(teams: T::Array[::Teams::Team]).returns(T::Array[::String]) }
+    def validation_errors(teams); end
+
+    private
+
+    sig { params(team: ::Teams::Team).returns(T.attached_class) }
+    def register_team(team); end
+
+    sig { returns(T::Hash[T.nilable(::String), T::Hash[::Class, ::Teams::Plugin]]) }
+    def registry; end
+  end
+end
+
+module Teams::Plugins; end
+
+class Teams::Plugins::Identity < ::Teams::Plugin
+  sig { returns(::Teams::Plugins::Identity::IdentityStruct) }
+  def identity; end
+
+  class << self
+    sig { override.params(teams: T::Array[::Teams::Team]).returns(T::Array[::String]) }
+    def validation_errors(teams); end
+  end
+end
+
+class Teams::Plugins::Identity::IdentityStruct < ::Struct
+  def name; end
+  def name=(_); end
+
+  class << self
+    def [](*_arg0); end
+    def inspect; end
+    def members; end
+    def new(*_arg0); end
+  end
+end
+
+class Teams::Team
+  sig { params(config_yml: T.nilable(::String), raw_hash: T::Hash[T.untyped, T.untyped]).void }
+  def initialize(config_yml:, raw_hash:); end
+
+  sig { params(other: ::Object).returns(T::Boolean) }
+  def ==(other); end
+
+  sig { returns(T.nilable(::String)) }
+  def config_yml; end
+
+  def eql?(*args, &blk); end
+
+  sig { returns(::Integer) }
+  def hash; end
+
+  sig { returns(::String) }
+  def name; end
+
+  sig { returns(T::Hash[T.untyped, T.untyped]) }
+  def raw_hash; end
+
+  sig { returns(::String) }
+  def to_tag; end
+
+  class << self
+    sig { params(raw_hash: T::Hash[T.untyped, T.untyped]).returns(::Teams::Team) }
+    def from_hash(raw_hash); end
+
+    sig { params(config_yml: ::String).returns(::Teams::Team) }
+    def from_yml(config_yml); end
+  end
+end
+
+Teams::UNKNOWN_TEAM_STRING = T.let(T.unsafe(nil), String)