cleo_codeowners 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0b451268ca7f9665ef4508901f64fb59e870948c24608555927cd4175e2cd5b7
+  data.tar.gz: f845e65d47b0e85f6c37e113b9d281a857ad07cd2506bc961a5797395abcbddf
+SHA512:
+  metadata.gz: eff3685362b27dbb5ca99c070ee274046c4f85f887e0a8680f705e8631caec387d6d6fd9d6cb7b97a9aefdd1b1f48c935bd399a618c51200b9731dd62061e3d5
+  data.tar.gz: 37f6cf695c019c07957cc630e09ab9b0e729065c25b02747a685a540b10d443b757d5776fb914b212d5eef15339a814370c2828a65ab4fd982ddcd831ae35cba

data/README.md

@@ -0,0 +1,125 @@
+# Cleo Codeowners
+
+Manage your github CODEOWNERS files across multiple teams and features.
+
+## Summary
+
+`cleo_codeowners` builds GitHub CODEOWNERS from small YAML files. Keep owners, features, and file globs in `.cleo/codeowners/**/*.yml`; generate `.github/CODEOWNERS` and `.github/CODEOWNERS-HUMAN`.
+
+## Installation
+
+```sh
+gem install cleo_codeowners
+```
+
+Or add it to your Gemfile:
+
+```ruby
+gem "cleo_codeowners"
+```
+
+In Rails, the gem adds a rake task:
+
+```sh
+bin/rails codeowners:generate
+```
+
+## Configuration
+
+Set the GitHub organization name before generating CODEOWNERS.
+
+In a Rails app, add an initializer:
+
+```ruby
+# config/initializers/codeowners.rb
+Codeowners.configure do |config|
+  config.organization_name = "my_org"
+end
+```
+
+In a non-Rails app, configure Codeowners in the Rakefile while setting up the rake task:
+
+```ruby
+# Rakefile
+require "cleo_codeowners"
+
+Codeowners.configure do |config|
+  config.organization_name = "my_org"
+end
+
+task :environment
+
+load Gem.loaded_specs["cleo_codeowners"].full_gem_path + "/lib/tasks/codeowners.rake"
+```
+
+## Writing your codeowners files
+
+Create YAML files under `.cleo/codeowners/`.
+
+```yaml
+# .cleo/codeowners/features.yml
+features:
+  session management:
+    session expiry:
+  billing:
+```
+
+```yaml
+# .cleo/codeowners/owners.yml
+owners:
+  session management: identity-platform
+  billing: payments
+```
+
+Child features inherit their parent owner unless they define one.
+
+```yaml
+# .cleo/codeowners/files/session_management.yml
+files:
+  session management:
+    - /app/controllers/sessions/
+    - /app/models/session.rb
+  session expiry:
+    - /app/services/session_expiry/
+
+# .cleo/codeowners/files/billing.yml
+files:
+  billing:
+    - /app/controllers/billing/
+    - /app/models/invoice.rb
+```
+
+Generate:
+
+```sh
+bin/rails codeowners:generate
+```
+
+Inspect:
+
+```sh
+cleo-codeowners find_feature app/models/session.rb
+cleo-codeowners find_owner app/models/session.rb --glob
+cleo-codeowners find_unowned_files --pattern='app/**/*.rb' --exit-status-on-match=1
+cleo-codeowners find_contributors "session management" --max-commits=100
+```
+
+## Development
+
+Requires Ruby `>= 3.2.0`.
+
+Install missing gems:
+
+```sh
+gem install rake thor activesupport mocha minitest
+```
+
+Run tests:
+
+```sh
+rake test
+```
+
+## License
+
+MIT

data/cleo_codeowners.gemspec

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative 'lib/cleo_codeowners/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'cleo_codeowners'
+  spec.version = CleoCodeowners::VERSION
+  spec.authors = %w[@agentAngelope @bodacious @sldblog]
+
+  spec.summary = 'Cleo CODEOWNERS tooling'
+  spec.description = 'Tools for reading Cleo CODEOWNERS definitions and generating GitHub CODEOWNERS files.'
+  spec.homepage = 'https://github.com/meetcleo/meetcleo'
+  spec.license = 'MIT'
+  spec.required_ruby_version = '>= 3.2.0'
+
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files =
+    Dir.glob("{#{File.basename(__FILE__)},README.md,lib/**/*,exe/*}", File::FNM_DOTMATCH).select do |path|
+      File.file?(path) && !File.symlink?(path)
+    end
+
+  spec.bindir = 'exe'
+  spec.executables = ['cleo-codeowners']
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'activesupport'
+  spec.add_dependency 'rake'
+  spec.add_dependency 'thor'
+end

data/exe/cleo-codeowners

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'codeowners/cli'
+
+Codeowners::CLI.start(ARGV)

data/lib/cleo_codeowners/railtie.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'rails/railtie'
+
+module CleoCodeowners
+  class Railtie < Rails::Railtie
+    rake_tasks do
+      load File.expand_path('../tasks/codeowners.rake', __dir__)
+    end
+  end
+end

data/lib/cleo_codeowners/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module CleoCodeowners
+  VERSION = '0.1.0'
+end

data/lib/cleo_codeowners.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative 'cleo_codeowners/version'
+require_relative 'codeowners'
+require_relative 'cleo_codeowners/railtie' if defined?(Rails::Railtie)

data/lib/codeowners/cli.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/enumerable'
+require 'active_support/core_ext/string/inflections'
+require 'English'
+require 'pathname'
+require 'thor'
+require_relative '../codeowners'
+
+module Codeowners
+  class CLI < Thor
+    def self.exit_on_failure?
+      true
+    end
+
+    desc 'find_files feature (glob)', 'Find all files under a particular feature, matching the GLOB file pattern'
+    def find_files(feature, glob = '*')
+      files = DefinitionsFile.new.feature_paths(feature:).select { |file| file.fnmatch?(glob) }
+      puts files.join("\n")
+    end
+
+    desc 'find_test_files feature', 'Find all test files under a particular feature'
+    def find_test_files(feature)
+      find_files(feature, '*_test.rb')
+    end
+
+    desc 'find_contributors FEATURE', 'Find top contributors for a feature based on git history'
+    method_option :max_commits, type: :numeric, default: 50, desc: 'Maximum number of commits to analyze'
+    def find_contributors(feature)
+      contributor_finder = ContributorFinder.new(max_commits: options[:max_commits])
+      contributors = contributor_finder.find_contributors(feature:)
+
+      if contributors.empty?
+        puts "No contributors found for feature '#{feature}'"
+        exit(0)
+      end
+
+      first_date = contributors.filter_map(&:first_commit_date).min
+      last_date = contributors.filter_map(&:last_commit_date).max
+      date_range = first_date && last_date ? "#{first_date} to #{last_date}" : 'N/A'
+      total_commits = contributors.sum(&:commits)
+
+      puts "Top contributors for feature '#{feature}'"
+      puts "Analyzed: last #{options[:max_commits]} commits (#{date_range})"
+      puts "Total commits: #{total_commits}"
+      puts
+
+      table_format = '%-30s %10s %10s %15s %8s'
+      puts format(table_format, 'GitHub Username', 'Additions', 'Deletions', 'Lines Changed', 'Commits')
+      puts '-' * 81
+      contributors.each do |contributor|
+        puts format(
+          table_format,
+          contributor.username,
+          contributor.additions,
+          contributor.deletions,
+          contributor.lines_changed,
+          contributor.commits
+        )
+      end
+    end
+
+    desc 'find_owner filepath', 'Find who owns a given file'
+    method_option :glob, type: :boolean, aliases: '-g', desc: 'Output the pattern matched'
+    def find_owner(filepath)
+      codeowners_file = CodeownersFile.new
+      owner_finder = OwnerFinder.new(codeowners_file:)
+      ownership = owner_finder.find_ownership_for_file(filepath:)
+      owners = ownership&.owners
+
+      unless owners&.any?
+        puts 'No owners found!'
+        exit(1)
+      end
+
+      output = owners.join(' ')
+      output << " #{ownership.glob}" if options[:glob]
+
+      puts output
+    end
+
+    desc 'find_owned_files OWNER', 'Find files matched to a given OWNER in the CODEOWNERS file'
+    method_option :pattern, type: :string, default: '**/*', desc: 'Pattern to match files against'
+    def find_owned_files(owner)
+      warn_against_global_glob_pattern if options[:pattern] == '**/*'
+
+      codeowners_file = CodeownersFile.new
+      owner_finder = OwnerFinder.new(codeowners_file:)
+      owned_files = Dir.glob(options[:pattern]).select do |filepath|
+        next unless Pathname.new(filepath).file?
+        next unless owner_finder.find_owners_for_file(filepath:).include?(owner)
+
+        filepath
+      end
+
+      owner_long_name = Owner.new(owner).long_name
+      if owned_files.any?
+        puts "#{owned_files.length} #{'file'.pluralize(owned_files.length)} found belonging to owner #{owner_long_name}"
+        puts owned_files
+      else
+        puts "No files found belonging to owner #{owner_long_name}"
+      end
+    end
+
+    desc 'find_unowned_files', 'Find files in the repo that are not marked with an owner in CODEOWNERS'
+    method_option :pattern, type: :string, default: '**/*', desc: 'Pattern to match files against'
+    method_option :exit_status_on_match, type: :numeric, default: 0, desc: 'What exit status should I return on match?'
+    method_option :output, type: :string, aliases: '-o', desc: 'Output file path (disables color codes)'
+    def find_unowned_files
+      warn_against_global_glob_pattern if options[:pattern] == '**/*'
+
+      codeowners_file = CodeownersFile.new
+      pattern = options[:pattern]
+
+      git_ls_files_pattern = pattern == '**/*' ? '.' : pattern
+      git_tracked_files = `git ls-files #{git_ls_files_pattern} 2>&1`
+      unless $CHILD_STATUS.success?
+        warn "Failed to run git ls-files: #{git_tracked_files}"
+        exit(1)
+      end
+
+      filepaths = git_tracked_files.split("\n").select do |filepath|
+        filepath_obj = Pathname.new(filepath)
+        next if filepath_obj.directory?
+
+        codeowners_file.globs.none? { |glob| glob.match?(filepath) }
+      end
+
+      output_stream = options[:output] ? File.open(options[:output], 'w') : $stdout
+      use_colors = options[:output].nil?
+
+      begin
+        if filepaths.empty?
+          output_with_color(output_stream, use_colors, "\e[32m", "No unowned files found in #{options[:pattern]}")
+          exit(0)
+        else
+          truncated_paths = truncate_to_unowned_directories(filepaths)
+          output_with_color(output_stream, use_colors, "\e[31m",
+                            "The following #{'path'.pluralize(truncated_paths.length)} are not included in the CODEOWNERS file:")
+          truncated_paths.each do |filepath|
+            output_with_color(output_stream, use_colors, "\e[31m", filepath)
+          end
+          exit(options[:exit_status_on_match])
+        end
+      ensure
+        output_stream.close if options[:output]
+      end
+    end
+
+    desc 'find_feature filepath', 'Find which feature a given file belongs to'
+    def find_feature(filepath)
+      feature = DefinitionsFile.new.find_feature_for_file(path: filepath)
+      if feature
+        puts feature
+      else
+        puts "No feature found for #{filepath}"
+        exit(1)
+      end
+    end
+
+    desc 'find_features filepath', 'Find all matching features a given file belongs to'
+    method_option :show_path, type: :boolean, default: false, desc: 'Print the path (useful when finding many paths)'
+    def find_features(filepath)
+      feature_matches = DefinitionsFile.new.find_features_for_file(path: filepath)
+      if feature_matches.any?
+        feature_matches.each do |match|
+          print = []
+          print << filepath if options[:show_path]
+          print << match.feature
+          print << match.path_pattern
+          puts print.join(',')
+        end
+      else
+        puts "No feature found for #{filepath}"
+        exit(1)
+      end
+    end
+
+    private
+
+    def output_with_color(stream, use_colors, color_code, text)
+      if use_colors
+        stream.puts "#{color_code} #{text} \e[0m"
+      else
+        stream.puts text
+      end
+    end
+
+    def truncate_to_unowned_directories(filepaths)
+      return [] if filepaths.empty?
+
+      unowned_set = filepaths.to_set
+      result = []
+      processed_dirs = Set.new
+
+      directories = filepaths.map do |filepath|
+        File.dirname(filepath)
+      end.uniq.sort_by { |directory| directory.count('/') }
+
+      directories.each do |directory|
+        next if directory == '.'
+        next if processed_dirs.any? { |processed| directory.start_with?("#{processed}/") }
+
+        git_files_in_dir = `git ls-files -- '#{directory}/' 2>&1`.split("\n")
+        next unless $CHILD_STATUS.success?
+        next if git_files_in_dir.empty?
+
+        git_files_in_dir.select! { |file| File.file?(file) }
+
+        if git_files_in_dir.all? { |file| unowned_set.include?(file) }
+          result << "#{directory}/"
+          processed_dirs << directory
+        end
+      end
+
+      filepaths.each do |filepath|
+        result << filepath unless processed_dirs.any? { |directory| filepath.start_with?("#{directory}/") }
+      end
+
+      result.sort.uniq
+    end
+
+    def warn_against_global_glob_pattern
+      warn <<~WARNING
+        Scanning all files in this repository (--pattern=**/*) may take a while...
+        You may want to use a specific glob pattern e.g. (--pattern=app/models/**/*.rb)
+      WARNING
+    end
+  end
+end

data/lib/codeowners/codeowners_file.rb

@@ -0,0 +1,36 @@
+# typed: false
+
+# frozen_string_literal: true
+
+module Codeowners
+  # Parses a Codeowners file
+  class CodeownersFile
+    require 'forwardable'
+    require_relative 'glob'
+    require_relative 'ownership'
+
+    extend Forwardable
+
+    attr_reader :source
+    private :source
+
+    def_delegators :source, :lines, :to_s
+
+    # @param [String] codeowners_source A String containing the readlines from the CODEOWNERS file
+    def initialize(codeowners_source = File.read('./.github/CODEOWNERS'))
+      @source = codeowners_source
+    end
+
+    def ownerships_reversed
+      @ownerships_reversed ||= ownerships.reverse
+    end
+
+    def ownerships
+      @ownerships ||= lines.map { |line| Ownership.new(*line.to_s.split) }
+    end
+
+    def globs
+      @globs ||= lines.map { |line| Glob.new(line.to_s.split.first) }
+    end
+  end
+end

data/lib/codeowners/configuration.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Codeowners
+  # Stores configuration options for the Codeowners gem.
+  class Configuration
+    ##
+    # Organization/team name strings should begin with an @ symbol
+    AT_PREFIX = '@'
+    private_constant :AT_PREFIX
+
+    ##
+    # Raised when a required configuration value is missing
+    class MissingConfigurationError < Error; end
+
+    def self.instance
+      @instance ||= new
+    end
+
+    def self.reset_singleton_instance!
+      @instance = nil
+    end
+
+    ##
+    # @param [String] organization_name the name of the Github organization
+    def initialize(organization_name: nil)
+      self.organization_name = organization_name
+    end
+
+    ##
+    # The organization name for teams
+    # @return [String] the name of the organization
+    def organization_name
+      raise MissingConfigurationError, 'Organization name is required' if @organization_name.nil?
+
+      @organization_name.dup
+    end
+
+    ##
+    # Set the default organization name for teams
+    # @param [String] value the name of the organization
+    def organization_name=(value)
+      value = value.to_s.dup
+      value.prepend(AT_PREFIX) unless value.start_with?(AT_PREFIX)
+      @organization_name = value
+    end
+  end
+end

data/lib/codeowners/contributor_finder.rb

@@ -0,0 +1,174 @@
+# typed: false
+# frozen_string_literal: true
+
+require 'json'
+require 'open3'
+require_relative 'definitions_file'
+
+module Codeowners
+  class ContributorFinder
+    DEFAULT_MAX_COMMITS = 50
+
+    ContributorStats = Data.define(:additions, :deletions, :commits, :dates)
+    Contributor = Data.define(:email, :username, :lines_changed, :additions, :deletions, :commits, :first_commit_date,
+                              :last_commit_date)
+
+    def initialize(definitions_file: DefinitionsFile.new, max_commits: DEFAULT_MAX_COMMITS)
+      @definitions_file = definitions_file
+      @max_commits = max_commits
+      @email_to_username_cache = {}
+    end
+
+    def find_contributors(feature:)
+      file_paths = collect_feature_files(feature)
+
+      return [] if file_paths.empty?
+
+      contributors = analyse_git_history(file_paths)
+      contributors.sort_by(&:lines_changed).reverse
+    end
+
+    private
+
+    attr_reader :definitions_file, :max_commits, :email_to_username_cache
+
+    def collect_feature_files(feature)
+      files = definitions_file.feature_paths(feature:)
+
+      subfeatures = find_all_subfeatures(feature)
+      subfeatures.each do |subfeature|
+        files.concat(definitions_file.feature_paths(feature: subfeature))
+      end
+
+      files.uniq.map(&:to_s)
+    end
+
+    def find_all_subfeatures(parent_feature, collected = [])
+      features_config = definitions_file.features_config
+      return collected unless features_config[parent_feature].is_a?(Hash)
+
+      features_config[parent_feature].each_key do |subfeature|
+        collected << subfeature
+        find_all_subfeatures(subfeature, collected)
+      end
+
+      collected
+    end
+
+    def analyse_git_history(file_paths)
+      return [] if file_paths.empty?
+
+      max_commits_str = max_commits.to_i
+      # Format: commit_hash|author_email|date
+      # Followed by numstat lines: additions\tdeletions\tfilename
+      git_args = ['git', 'log', '--numstat', "--max-count=#{max_commits_str}", '--format=%H|%ae|%ad', '--date=short',
+                  '--']
+      git_args.concat(file_paths)
+
+      output, status = Open3.capture2(*git_args, err: %i[child out])
+      unless status.success?
+        warn('Failed to run git log', output:)
+        return []
+      end
+
+      parse_git_log(output)
+    end
+
+    # Parses git log output in the format:
+    # commit_hash|email|date
+    # <blank line>
+    # additions\tdeletions\tfilename
+    # additions\tdeletions\tfilename
+    # <blank line>
+    # commit_hash|email|date
+    # ...
+    def parse_git_log(output)
+      contributors_by_email = Hash.new { ContributorStats.new(additions: 0, deletions: 0, commits: 0, dates: []) }
+
+      current_email = nil
+      output.each_line do |line|
+        line.strip!
+        next if line.empty?
+
+        if commit_line?(line)
+          current_email = parse_commit_line(line, contributors_by_email)
+        elsif numstat_line?(line) && current_email
+          parse_numstat_line(line, contributors_by_email, current_email)
+        end
+      end
+
+      build_contributor_records(contributors_by_email)
+    end
+
+    def commit_line?(line)
+      line.include?('|')
+    end
+
+    def parse_commit_line(line, contributors_by_email)
+      _commit_hash, email, date = line.split('|')
+      stats = contributors_by_email[email]
+      contributors_by_email[email] = stats.with(
+        commits: stats.commits + 1,
+        dates: stats.dates + [date]
+      )
+      email
+    end
+
+    def numstat_line?(line)
+      line.match?(/^\d+\s+\d+\s+/)
+    end
+
+    def parse_numstat_line(line, contributors_by_email, email)
+      additions, deletions = line.split(/\s+/)
+      # Binary files show '-' for additions/deletions, skip them
+      return if additions == '-' || deletions == '-'
+
+      stats = contributors_by_email[email]
+      contributors_by_email[email] = stats.with(
+        additions: stats.additions + additions.to_i,
+        deletions: stats.deletions + deletions.to_i
+      )
+    end
+
+    def build_contributor_records(contributors_by_email)
+      contributors_by_email.map do |email, stats|
+        Contributor.new(
+          email:,
+          username: resolve_email_to_username(email),
+          lines_changed: stats.additions + stats.deletions,
+          additions: stats.additions,
+          deletions: stats.deletions,
+          commits: stats.commits,
+          first_commit_date: stats.dates.min,
+          last_commit_date: stats.dates.max
+        )
+      end
+    end
+
+    def resolve_email_to_username(email)
+      return email_to_username_cache[email] if email_to_username_cache.key?(email)
+
+      username = fetch_github_username(email)
+      email_to_username_cache[email] = username
+      username
+    end
+
+    def fetch_github_username(email)
+      query_param = "author-email:#{email}+repo:meetcleo/meetcleo"
+      gh_args = [
+        'gh', 'api',
+        "/search/commits?q=#{query_param}",
+        '--jq', '.items[0].author.login'
+      ]
+
+      result, status = Open3.capture2(*gh_args, err: File::NULL)
+      result = result.strip
+
+      if status.success? && !result.empty? && result != 'null'
+        result
+      else
+        email.split('@').first
+      end
+    end
+  end
+end

data/lib/codeowners/definitions_file.rb

@@ -0,0 +1,90 @@
+# typed: false
+# frozen_string_literal: true
+
+require 'active_support/core_ext/hash/deep_merge'
+require 'pathname'
+require 'yaml'
+
+module Codeowners
+  # Parses Cleo Codeowners YAML files
+  class DefinitionsFile
+    # @param [String] definition_glob String containing the glob pattern for the Cleo codeowner YAML files
+    def initialize(definition_glob = '.cleo/codeowners/**/*.y*ml')
+      @definition = Dir[definition_glob].inject({}) do |yaml, filepath|
+        yaml.deep_merge(YAML.load_file(filepath))
+      end
+    end
+
+    attr_reader :definition
+
+    def features_config
+      definition['features'] || {}
+    end
+
+    def owners_config
+      definition['owners'] || {}
+    end
+
+    def file_config
+      definition['files'] || {}
+    end
+
+    # Finds files defined under a feature, expands all globs, and returns all of them
+    # @return [Array,<Pathname>]
+    def feature_paths(feature:, directory: nil)
+      relative_globs = Array(file_config[feature]).map { |path| "./#{path}" }
+      resolve_local_paths(relative_globs:, directory: directory || Pathname.pwd)
+    end
+
+    # Finds a feature the file belongs to
+    # @return [nil, String]
+    def find_feature_for_file(path:)
+      return nil unless path
+
+      target_path = File.join('.', path)
+      file_config.each do |feature, paths|
+        next unless paths
+
+        paths.each do |feature_path|
+          path_pattern = File.join('.', feature_path)
+          path_pattern = "#{path_pattern}/*" if path_pattern.end_with?('/')
+          path_pattern.gsub!('//', '/')
+
+          return feature if File.fnmatch(path_pattern, target_path)
+        end
+      end
+
+      nil
+    end
+
+    Match = Data.define(:feature, :path_pattern)
+
+    # Finds a feature the file belongs to
+    # @return Array
+    def find_features_for_file(path:)
+      return [] unless path
+
+      target_path = File.join('.', path)
+      file_config.filter_map do |feature, paths|
+        next unless paths
+
+        paths.filter_map do |feature_path|
+          path_pattern = File.join('.', feature_path)
+          path_pattern = "#{path_pattern}/*" if path_pattern.end_with?('/')
+          path_pattern.gsub!('//', '/')
+
+          Match.new(feature, path_pattern) if File.fnmatch(path_pattern, target_path)
+        end
+      end.flatten.uniq
+    end
+
+    private
+
+    def resolve_local_paths(directory:, relative_globs:)
+      directory
+        .glob(relative_globs)
+        .flat_map { |pathname| pathname.directory? ? pathname.glob('**/*') : pathname }
+        .map { |pathname| pathname.relative_path_from(directory) }
+    end
+  end
+end

data/lib/codeowners/generator.rb

@@ -0,0 +1,172 @@
+# typed: false
+# frozen_string_literal: true
+
+module Codeowners
+  class Generator
+    DEFAULT_OUTPUT_PATH = '.github/CODEOWNERS'
+    DEFAULT_HUMAN_OUTPUT_PATH = '.github/CODEOWNERS-HUMAN'
+
+    def initialize(
+      definitions_file: DefinitionsFile.new,
+      output_path: DEFAULT_OUTPUT_PATH,
+      human_output_path: DEFAULT_HUMAN_OUTPUT_PATH
+    )
+      @definitions_file = definitions_file
+      @output_path = output_path
+      @human_output_path = human_output_path
+      @calculated_owners = []
+      @all_features = []
+    end
+
+    def call
+      File.open(output_path, 'w') do |output_file|
+        File.open(human_output_path, 'w') do |output_human_file|
+          @output_file = output_file
+          @output_human_file = output_human_file
+
+          output(blurb, depth: 0)
+          calculate_owners_and_output_in_human_format(features: top_level_features)
+          validate_owners_in_features
+          output_in_machine_format
+        end
+      end
+    ensure
+      @output_file = nil
+      @output_human_file = nil
+    end
+
+    private
+
+    attr_reader :all_features,
+                :calculated_owners,
+                :definitions_file,
+                :human_output_path,
+                :output_file,
+                :output_human_file,
+                :output_path
+
+    def owners
+      @owners ||= definitions_file.owners_config
+    end
+
+    def top_level_features
+      @top_level_features ||= definitions_file.features_config
+    end
+
+    def files
+      @files ||= definitions_file.file_config
+    end
+
+    def calculate_owners_and_output_in_human_format(features:, current_owner: nil, depth: 0)
+      return unless present?(features)
+
+      features.sort_by(&:first).each do |feature, children|
+        output(feature.upcase, depth:)
+        owner = owners.fetch(feature, current_owner)
+        feature_files = files[feature]
+
+        if blank?(owner)
+          raise "Please assign an owner for #{feature} in owners.yaml!"
+        elsif blank?(feature_files) && blank?(children)
+          raise "Please assign files or child features to #{feature}, or remove it!"
+        else
+          all_features << feature
+        end
+
+        if owner == 'unowned'
+          output('Currently unowned', depth:)
+        else
+          output("Currently owned by @meetcleo/#{owner}", depth:)
+        end
+
+        if present?(feature_files)
+          feature_files.sort.uniq.each do |file|
+            record_calculated_owner(file, Owner.new(owner).long_name)
+            output("#{file} #{Owner.new(owner).long_name}", depth:, comment: false)
+          end
+        end
+
+        calculate_owners_and_output_in_human_format(features: children, current_owner: owner, depth: depth + 1)
+      end
+    end
+
+    def output(string, depth:, comment: true)
+      string.split("\n").each do |line|
+        line = if comment
+                 "#{' ' * (depth * 2)}# #{line}"
+               else
+                 "#{' ' * ((depth + 1) * 2)}#{line}"
+               end
+        output_human_file << line.rstrip << "\n"
+      end
+    end
+
+    def record_calculated_owner(path, owner)
+      calculated_owners.push({ path:, owner: })
+    end
+
+    def output_in_machine_format
+      file_rules, folder_rules = calculated_owners.partition { |owner| owner[:path].include?('.') }
+      group_by_path_segments_and_output(folder_rules)
+      group_by_path_segments_and_output(file_rules)
+    end
+
+    def group_by_path_segments_and_output(rules)
+      grouped_by_path_segments_number = rules
+                                        .group_by { |owner| sanitised_path(owner[:path]).split('/').reject(&:empty?).size }
+                                        .each_value do |rule|
+        rule.sort_by! do |owner|
+          owner[:path]
+        end
+      end
+                                                                                                                                        .sort
+                                                                                                                                        .to_h
+
+      grouped_by_path_segments_number
+        .each_value
+        .map { |files_and_owners| files_and_owners.group_by { |owner| owner[:path] } }
+        .each do |files_and_owners|
+          files_and_owners.each do |file, owners_list|
+            rule_owners = owners_list.map { |owner| owner[:owner] }.uniq.sort
+            output_file << "#{sanitised_path(file)} #{rule_owners.join(' ')}\n"
+          end
+        end
+    end
+
+    def blurb
+      <<~BLURB
+        This CODEOWNERS file is grouped by feature, using Github teams (a squad may
+        have one or more Github teams).
+
+        Please use the codeowners:generate rake task and the .cleo/codeowners yaml
+        configuration files to update this file.
+      BLURB
+    end
+
+    def sanitised_path(path)
+      return path if path.start_with?('/')
+
+      "/#{path}"
+    end
+
+    def validate_owners_in_features
+      features_missing_from_features_yaml = files.keys - all_features
+      return if features_missing_from_features_yaml.empty?
+
+      raise "The following features are missing from features.yaml:\n#{
+        features_missing_from_features_yaml.join("\n")
+      }"
+    end
+
+    def blank?(value)
+      return true if value.nil? || value == false
+      return value.strip.empty? if value.is_a?(String)
+
+      value.respond_to?(:empty?) && value.empty?
+    end
+
+    def present?(value)
+      !blank?(value)
+    end
+  end
+end

data/lib/codeowners/glob.rb

@@ -0,0 +1,45 @@
+# typed: false
+
+# frozen_string_literal: true
+
+module Codeowners
+  require 'delegate'
+
+  class Glob
+    require 'forwardable'
+    extend Forwardable
+
+    # The glob pattern this glob will match
+    #
+    # @return [String]
+    # @see #match?
+    attr_reader :pattern
+
+    def_delegator :File, :fnmatch, :fnmatch
+    def_delegator :pattern, :to_s
+
+    def initialize(string)
+      @pattern = normalize_string(string)
+    end
+
+    # Does this glob match the given filepath?
+    # @param [String] filepath to match against
+    # @note
+    #   Don't use `FNM_CASEFOLD`, GitHub uses a case sensitive file system.
+    #   Don't use `FNM_EXTGLOB`, GitHub CODEOWNERS files don't support it.
+    #   Don't use `FNM_PATHNAME`, we want to match `*` against '/'.
+    #
+    # @see https://docs.ruby-lang.org/en/3.3/File.html#method-c-fnmatch
+    # @return [Boolean]
+    def match?(filepath)
+      fnmatch(pattern, filepath, File::FNM_DOTMATCH)
+    end
+
+    private
+
+    def normalize_string(string)
+      string.to_s.delete_prefix('/') # remove leading slashes
+            .gsub(%r{/\Z}, '/**') # replace trailing slash with a recursive wildcard
+    end
+  end
+end

data/lib/codeowners/owner.rb

@@ -0,0 +1,40 @@
+# typed: false
+
+# frozen_string_literal: true
+
+module Codeowners
+  class Owner
+    ##
+    # Name of team in CODEOWNERS file (e.g. @meetcleo/chat)
+    # @return [String]
+    attr_reader :name
+    alias long_name name
+
+    ##
+    # Name of team in config files (e.g. chat)
+    # @return [String]
+    attr_reader :short_name
+
+    # @param [String] name_string Name of team in CODEOWNERS file (e.g. `"@meetcleo/chat"`)
+    def initialize(name_string)
+      name_string = "#{organization_name}/#{name_string}" unless name_string.start_with?(organization_name)
+      @name = name_string
+      @short_name = name_string.split('/').last
+    end
+
+    # Prefix for team names in the CODEOWNERS file
+    # @return [String]
+    def organization_name = Configuration.instance.organization_name
+
+    # Does this string match the name of the owner?
+    # @return [Boolean]
+    def match?(compare_string)
+      compare_string = "#{organization_name}/#{compare_string}" unless compare_string.start_with?(organization_name)
+      name == compare_string.to_s.downcase
+    end
+
+    def to_s
+      name.gsub(organization_name, '')
+    end
+  end
+end

data/lib/codeowners/owner_finder.rb

@@ -0,0 +1,35 @@
+# typed: false
+# frozen_string_literal: true
+
+module Codeowners
+  class OwnerFinder
+    attr_reader :codeowners_file
+    private :codeowners_file
+
+    def self.singleton(...)
+      @singleton ||= new(...)
+    end
+
+    def initialize(codeowners_file:)
+      @codeowners_file = codeowners_file
+    end
+
+    # Find the most likely owners of the file with the given filepath. Returns the owner name as an Array of Strings
+    # (e.g. ["card-1-be", "card-2-be"])
+    # @return [Array,<String>]
+    def find_owners_for_file(filepath:)
+      last_matching_ownership = find_ownership_for_file(filepath:)
+      return [] if last_matching_ownership.nil?
+
+      last_matching_ownership.owners.map(&:to_s)
+    end
+
+    # Find the most likely owners of the file with the given filepath. Returns
+    # @return [Ownership]
+    def find_ownership_for_file(filepath:)
+      codeowners_file.ownerships_reversed.find do |ownership|
+        ownership.glob_match?(filepath)
+      end
+    end
+  end
+end

data/lib/codeowners/ownership.rb

@@ -0,0 +1,40 @@
+# typed: false
+
+# frozen_string_literal: true
+
+module Codeowners
+  # The Ownership class represents an codeowners rule from a GitHub CODEOWNERS file.
+  # It includes methods to filter files matching the path expression and to check codeowners.
+  class Ownership
+    require 'forwardable'
+    extend Forwardable
+
+    require_relative 'glob'
+    require_relative 'owner'
+
+    # @return [Ownership::Glob] The path expression from the CODEOWNERS file
+    attr_reader :glob
+
+    # @return [Array<Codeowners::Owner>] The owners (team name) from the CODEOWNERS file
+    attr_reader :owners
+
+    # Initializes a new Ownership instance
+    #
+    # @param [String] glob The file path pattern from the CODEOWNERS file
+    # @param [Array<String>] owners The owners (team names) associated with the path expression
+    def initialize(glob, *owners)
+      @glob = Glob.new(glob)
+      @owners = owners.map { |owner| Owner.new(owner) }
+    end
+
+    # Checks if a given owner name matches the owner of this path expression
+    #
+    # @param owner_name [String] the owner name to check
+    # @return [Boolean] true if the given owner name matches, false otherwise
+    def owner?(owner_name)
+      owners.any? { |owner| owner.match?(owner_name) }
+    end
+
+    def_delegator :glob, :match?, :glob_match?
+  end
+end

data/lib/codeowners.rb

@@ -0,0 +1,23 @@
+# typed: false
+# frozen_string_literal: true
+
+module Codeowners
+  # Base error for all Codeowners errors
+  class Error < StandardError; end
+
+  require_relative 'codeowners/configuration'
+  require_relative 'codeowners/owner'
+  require_relative 'codeowners/glob'
+  require_relative 'codeowners/ownership'
+  require_relative 'codeowners/codeowners_file'
+  require_relative 'codeowners/owner_finder'
+  require_relative 'codeowners/definitions_file'
+  require_relative 'codeowners/contributor_finder'
+  require_relative 'codeowners/generator'
+
+  def self.configure(&block)
+    yield(Configuration.instance) if block
+
+    Configuration.instance
+  end
+end

data/lib/tasks/codeowners.rake

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require 'codeowners'
+
+namespace :codeowners do
+  desc 'Generates CODEOWNERS file from .cleo/codeowners'
+  task generate: [:environment] do
+    Codeowners::Generator.new.call
+  end
+end

metadata

@@ -0,0 +1,103 @@
+--- !ruby/object:Gem::Specification
+name: cleo_codeowners
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- "@agentAngelope"
+- "@bodacious"
+- "@sldblog"
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  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: rake
+  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: thor
+  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'
+description: Tools for reading Cleo CODEOWNERS definitions and generating GitHub CODEOWNERS
+  files.
+executables:
+- cleo-codeowners
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- cleo_codeowners.gemspec
+- exe/cleo-codeowners
+- lib/cleo_codeowners.rb
+- lib/cleo_codeowners/railtie.rb
+- lib/cleo_codeowners/version.rb
+- lib/codeowners.rb
+- lib/codeowners/cli.rb
+- lib/codeowners/codeowners_file.rb
+- lib/codeowners/configuration.rb
+- lib/codeowners/contributor_finder.rb
+- lib/codeowners/definitions_file.rb
+- lib/codeowners/generator.rb
+- lib/codeowners/glob.rb
+- lib/codeowners/owner.rb
+- lib/codeowners/owner_finder.rb
+- lib/codeowners/ownership.rb
+- lib/tasks/codeowners.rake
+homepage: https://github.com/meetcleo/meetcleo
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.13
+specification_version: 4
+summary: Cleo CODEOWNERS tooling
+test_files: []