code_teams 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 82e9081880258d807cdc9cb6393597d729e36ddb2cc0e91cc5f2179b52477d6a
+  data.tar.gz: ef5116c3487e50cb9987bf110e64410a5c343341db448df9a9c3400b8ee0feee
+SHA512:
+  metadata.gz: 74a20af786913be7e7a12a5ad64c1605ddeca3ba895cb1733095d1b4762ffc26a08798073697c25d9939aa59c94174badaae70e37e7306b24b7ba2e62aac67d3
+  data.tar.gz: d070407e8113266e5f364c7abc3485bee7bc15bdaa5a25d46e98c5066e9ccd4561ef1b9ad9808adb0ef9df4eebf613838a74bc8d78587795b8d97bec99837b19

data/README.md

@@ -0,0 +1,92 @@
+# CodeTeams
+
+This gem is a simple, low-dependency, plugin-based manager for teams within a codebase.
+
+## Usage
+
+To use `code_teams`, add YML files in `config/teams` that start with structure:
+`config/teams/my_team.yml`
+```yml
+name: My Team
+```
+
+`code_teams` leverages a plugin system because every organization's team practices are different. Say your organization uses GitHub and wants to ensure every team YML files has a GitHub owner. To do this, you create a plugin:
+
+```ruby
+class MyGithubPlugin < CodeTeams::Plugin
+  extend T::Sig
+  extend T::Helpers
+
+  GithubStruct = Struct.new(:team, :members)
+
+  sig { returns(GithubStruct) }
+  def github
+    raw_github = @team.raw_hash['github'] || {}
+
+    GithubStruct.new(
+      raw_github['team'],
+      raw_github['members'] || []
+    )
+  end
+
+  def member?(user)
+    members = github.members
+    return false unless members
+
+    members.include?(user)
+  end
+
+  sig { override.params(teams: T::Array[CodeTeams::Team]).returns(T::Array[String]) }
+  def self.validation_errors(teams)
+    errors = T.let([], T::Array[String])
+
+    teams.each do |team|
+      errors << missing_key_error_message(team, 'github.team') if self.for(team).github.team.nil?
+    end
+
+    errors
+  end
+end
+```
+
+After adding the proper GitHub information to the team YML:
+```yml
+name: My Team
+github:
+  team: '@org/my-team
+  members:
+    - member1
+    - member2
+```
+
+1) You can now use the following API to get GitHub information about that team:
+```ruby
+team = CodeTeams.find('My Team')
+MyGithubPlugin.for(team).github
+```
+2) Running team validations (see below) will ensure all teams have a GitHub team specified
+
+Your plugins can be as simple or as complex as you want. Here are some other things we use plugins for:
+- Identifying which teams own which feature flags
+- Mapping teams to specific portions of the code through `code_ownership`
+- Allowing teams to protect certain files and require approval on modification of certain files
+- Specifying owned dependencies (ruby gems, javascript packages, and more)
+- Specifying how to get in touch with the team via slack (their channel and handle)
+
+## Configuration
+You'll want to ensure that all teams are valid in your CI environment. We recommend running code like this in CI:
+```ruby
+require 'code_teams'
+errors = ::CodeTeams.validation_errors(::CodeTeams.all)
+if errors.any?
+  abort <<~ERROR
+    Team validation failed with the following errors:
+    #{errors.join("\n")}
+  ERROR
+end
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome!
+

data/lib/code_teams/plugin.rb

@@ -0,0 +1,67 @@
+# typed: strict
+
+module CodeTeams
+  # Plugins allow a client to add validation on custom keys in the team YML.
+  # For now, only a single plugin is allowed to manage validation on a top-level key.
+  # In the future we can think of allowing plugins to be gracefully merged with each other.
+  class Plugin
+    extend T::Helpers
+    extend T::Sig
+
+    abstract!
+
+    sig { params(team: Team).void }
+    def initialize(team)
+      @team = team
+    end
+
+    sig { params(base: T.untyped).void }
+    def self.inherited(base) # rubocop:disable Lint/MissingSuper
+      all_plugins << T.cast(base, T.class_of(Plugin))
+    end
+
+    sig { returns(T::Array[T.class_of(Plugin)]) }
+    def self.all_plugins
+      @all_plugins ||= T.let(@all_plugins, T.nilable(T::Array[T.class_of(Plugin)]))
+      @all_plugins ||= []
+      @all_plugins
+    end
+
+    sig { params(teams: T::Array[Team]).returns(T::Array[String]) }
+    def self.validation_errors(teams) # rubocop:disable Lint/UnusedMethodArgument
+      []
+    end
+
+    sig { params(team: Team).returns(T.attached_class) }
+    def self.for(team)
+      register_team(team)
+    end
+
+    sig { params(team: Team, key: String).returns(String) }
+    def self.missing_key_error_message(team, key)
+      "#{team.name} is missing required key `#{key}`"
+    end
+
+    sig { returns(T::Hash[T.nilable(String), T::Hash[Class, Plugin]]) }
+    def self.registry
+      @registry ||= T.let(@registry, T.nilable(T::Hash[String, T::Hash[Class, Plugin]]))
+      @registry ||= {}
+      @registry
+    end
+
+    sig { params(team: Team).returns(T.attached_class) }
+    def self.register_team(team)
+      # We pull from the hash since `team.name` uses the registry
+      team_name = team.raw_hash['name']
+
+      registry[team_name] ||= {}
+      registry_for_team = registry[team_name] || {}
+      registry[team_name] ||= {}
+      registry_for_team[self] ||= new(team)
+      T.unsafe(registry_for_team[self])
+    end
+
+    private_class_method :registry
+    private_class_method :register_team
+  end
+end

data/lib/code_teams/plugins/identity.rb

@@ -0,0 +1,37 @@
+# typed: true
+
+module CodeTeams
+  module Plugins
+    class Identity < Plugin
+      extend T::Sig
+      extend T::Helpers
+
+      IdentityStruct = Struct.new(:name)
+
+      sig { returns(IdentityStruct) }
+      def identity
+        IdentityStruct.new(
+          @team.raw_hash['name']
+        )
+      end
+
+      sig { override.params(teams: T::Array[CodeTeams::Team]).returns(T::Array[String]) }
+      def self.validation_errors(teams)
+        errors = T.let([], T::Array[String])
+
+        uniq_set = Set.new
+        teams.each do |team|
+          for_team = self.for(team)
+
+          if !uniq_set.add?(for_team.identity.name)
+            errors << "More than 1 definition for #{for_team.identity.name} found"
+          end
+
+          errors << missing_key_error_message(team, 'name') if for_team.identity.name.nil?
+        end
+
+        errors
+      end
+    end
+  end
+end

data/lib/code_teams.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+# typed: strict
+
+require 'yaml'
+require 'set'
+require 'pathname'
+require 'sorbet-runtime'
+require 'code_teams/plugin'
+require 'code_teams/plugins/identity'
+
+module CodeTeams
+  extend T::Sig
+
+  class IncorrectPublicApiUsageError < StandardError; end
+
+  UNKNOWN_TEAM_STRING = 'Unknown Team'
+
+  sig { returns(T::Array[Team]) }
+  def self.all
+    @all = T.let(@all, T.nilable(T::Array[Team]))
+    @all ||= for_directory('config/teams')
+  end
+
+  sig { params(name: String).returns(T.nilable(Team)) }
+  def self.find(name)
+    @index_by_name = T.let(@index_by_name, T.nilable(T::Hash[String, CodeTeams::Team]))
+    @index_by_name ||= begin
+      result = {}
+      all.each { |t| result[t.name] = t }
+      result
+    end
+
+    @index_by_name[name]
+  end
+
+  sig { params(dir: String).returns(T::Array[Team]) }
+  def self.for_directory(dir)
+    Pathname.new(dir).glob('**/*.yml').map do |path|
+      Team.from_yml(path.to_s)
+    rescue Psych::SyntaxError
+      raise IncorrectPublicApiUsageError, "The YML in #{path} has a syntax error!"
+    end
+  end
+
+  sig { params(teams: T::Array[Team]).returns(T::Array[String]) }
+  def self.validation_errors(teams)
+    Plugin.all_plugins.flat_map do |plugin|
+      plugin.validation_errors(teams)
+    end
+  end
+
+  sig { params(string: String).returns(String) }
+  def self.tag_value_for(string)
+    string.tr('&', ' ').gsub(/\s+/, '_').downcase
+  end
+
+  # Generally, you should not ever need to do this, because once your ruby process loads, cached content should not change.
+  # Namely, the YML files that are the source of truth for teams should not change, so we should not need to look at the YMLs again to verify.
+  # The primary reason this is helpful is for clients of CodeTeams who want to test their code, and each test context has different set of teams
+  sig { void }
+  def self.bust_caches!
+    @all = nil
+    @index_by_name = nil
+  end
+
+  class Team
+    extend T::Sig
+
+    sig { params(config_yml: String).returns(Team) }
+    def self.from_yml(config_yml)
+      hash = YAML.load_file(config_yml)
+
+      new(
+        config_yml: config_yml,
+        raw_hash: hash
+      )
+    end
+
+    sig { params(raw_hash: T::Hash[T.untyped, T.untyped]).returns(Team) }
+    def self.from_hash(raw_hash)
+      new(
+        config_yml: nil,
+        raw_hash: raw_hash
+      )
+    end
+
+    sig { returns(T::Hash[T.untyped, T.untyped]) }
+    attr_reader :raw_hash
+
+    sig { returns(T.nilable(String)) }
+    attr_reader :config_yml
+
+    sig do
+      params(
+        config_yml: T.nilable(String),
+        raw_hash: T::Hash[T.untyped, T.untyped]
+      ).void
+    end
+    def initialize(config_yml:, raw_hash:)
+      @config_yml = config_yml
+      @raw_hash = raw_hash
+    end
+
+    sig { returns(String) }
+    def name
+      Plugins::Identity.for(self).identity.name
+    end
+
+    sig { returns(String) }
+    def to_tag
+      CodeTeams.tag_value_for(name)
+    end
+
+    sig { params(other: Object).returns(T::Boolean) }
+    def ==(other)
+      if other.is_a?(CodeTeams::Team)
+        self.name == other.name
+      else
+        false
+      end
+    end
+
+    alias_method :eql?, :==
+
+    sig { returns(Integer) }
+    def hash # rubocop:disable Rails/Delegate
+      name.hash
+    end
+  end
+end

data/sorbet/config

@@ -0,0 +1,2 @@
+--dir
+.

data/sorbet/rbi/todo.rbi

@@ -0,0 +1,5 @@
+# This file is autogenerated. Do not edit it by hand. Regenerate it with:
+#   srb rbi todo
+
+# typed: strong
+module ::RSpec; end

metadata

@@ -0,0 +1,123 @@
+--- !ruby/object:Gem::Specification
+name: code_teams
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Gusto Engineers
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2022-06-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: sorbet-runtime
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: sorbet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A low-dependency gem for declaring and querying engineering teams
+email:
+- dev@gusto.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/code_teams.rb
+- lib/code_teams/plugin.rb
+- lib/code_teams/plugins/identity.rb
+- sorbet/config
+- sorbet/rbi/todo.rbi
+homepage: https://github.com/rubyatscale/code_teams
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/rubyatscale/code_teams
+  source_code_uri: https://github.com/rubyatscale/code_teams
+  changelog_uri: https://github.com/rubyatscale/code_teams/releases
+  allowed_push_host: https://rubygems.org
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.6'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.7
+signing_key: 
+specification_version: 4
+summary: A low-dependency gem for declaring and querying engineering teams
+test_files: []