code_ownership 2.0.0.pre.1-arm64-darwin → 2.0.0.pre.3-arm64-darwin

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eaf0d23097ced4e1034524765fda4bf2b67a76217b8cf7d90929147cef6f52d1
-  data.tar.gz: 70fc585836c0b596a2a6a9f75159eb03ffe7430dc226be65fc122fffed871237
+  metadata.gz: b2f959f149fbbace4157a6bcd12ac2d15f8a43d517fce8ea4d1898273059c4bc
+  data.tar.gz: 5c4d451d92e34a5f64fa4207ce9fe6099a512a80f3037e8c739be89fc6dca18b
 SHA512:
-  metadata.gz: 5652011eef699489ad876bee325fd66547e26d4cdfd14db17ba1b8f938c50c8e1e312df748bdbfd56b4d65c37b755a1977ad84f437c80047c6e7a52b84152f7f
-  data.tar.gz: b06751757a624cc8b1fbc6e8ddfa6a6fa9f56993cdfb223e5d1ddda6ba1cc94c03b8094302b9627f97390a7064dfd3d529d51447d47edce6bc8498065e26edb8
+  metadata.gz: 920fecf5b66a01c71c00f43dda6b613e215fc810e54fb1b6fd8c18eaf247266dc3f860676b2f7fce2da9ab2a0c4b2c5a416c83b96890a7cfba087d2308d50290
+  data.tar.gz: 14f964a70e0c750e826bffbd9cc84db851e0172abb2d062898b6923d17f0743e8ce44276d1f668e7dde81dce5a46098363c03c912924b6987be25e4255c53e4f

data/lib/code_ownership/cli.rb

@@ -95,6 +95,10 @@ module CodeOwnership
           options[:json] = true
         end
 
+        opts.on('--verbose', 'Output verbose information') do
+          options[:verbose] = true
+        end
+
         opts.on('--help', 'Shows this prompt') do
           puts opts
           exit
@@ -107,24 +111,7 @@ module CodeOwnership
         raise "Please pass in one file. Use `#{EXECUTABLE} for_file --help` for more info"
       end
 
-      team = CodeOwnership.for_file(files.first)
-
-      team_name = team&.name || 'Unowned'
-      team_yml = team&.config_yml || 'Unowned'
-
-      if options[:json]
-        json = {
-          team_name: team_name,
-          team_yml: team_yml
-        }
-
-        puts json.to_json
-      else
-        puts <<~MSG
-          Team: #{team_name}
-          Team YML: #{team_yml}
-        MSG
-      end
+      puts CodeOwnership::Private::ForFileOutputBuilder.build(file_path: files.first, json: !!options[:json], verbose: !!options[:verbose])
     end
 
     def self.for_team(argv)

data/lib/code_ownership/private/for_file_output_builder.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+# typed: strict
+
+module CodeOwnership
+  module Private
+    class ForFileOutputBuilder
+      extend T::Sig
+      private_class_method :new
+
+      sig { params(file_path: String, json: T::Boolean, verbose: T::Boolean).void }
+      def initialize(file_path:, json:, verbose:)
+        @file_path = file_path
+        @json = json
+        @verbose = verbose
+      end
+
+      sig { params(file_path: String, json: T::Boolean, verbose: T::Boolean).returns(String) }
+      def self.build(file_path:, json:, verbose:)
+        new(file_path: file_path, json: json, verbose: verbose).build
+      end
+
+      UNOWNED_OUTPUT = T.let(
+        {
+          team_name: 'Unowned',
+          team_yml: 'Unowned'
+        },
+        T::Hash[Symbol, T.untyped]
+      )
+
+      sig { returns(String) }
+      def build
+        result_hash = @verbose ? build_verbose : build_terse
+
+        return result_hash.to_json if @json
+
+        build_message_for(result_hash)
+      end
+
+      private
+
+      sig { returns(T::Hash[Symbol, T.untyped]) }
+      def build_verbose
+        result = CodeOwnership.for_file_verbose(@file_path)
+        return UNOWNED_OUTPUT if result.nil?
+
+        {
+          team_name: result[:team_name],
+          team_yml: result[:team_config_yml],
+          description: result[:reasons]
+        }
+      end
+
+      sig { returns(T::Hash[Symbol, T.untyped]) }
+      def build_terse
+        team = CodeOwnership.for_file(@file_path, from_codeowners: false, allow_raise: true)
+
+        if team.nil?
+          UNOWNED_OUTPUT
+        else
+          {
+            team_name: team.name,
+            team_yml: team.config_yml
+          }
+        end
+      end
+
+      sig { params(result_hash: T::Hash[Symbol, T.untyped]).returns(String) }
+      def build_message_for(result_hash)
+        messages = ["Team: #{result_hash[:team_name]}", "Team YML: #{result_hash[:team_yml]}"]
+        description_list = T.let(Array(result_hash[:description]), T::Array[String])
+        messages << build_description_message(description_list) unless description_list.empty?
+        messages.last << "\n"
+        messages.join("\n")
+      end
+
+      sig { params(reasons: T::Array[String]).returns(String) }
+      def build_description_message(reasons)
+        "Description:\n- #{reasons.join("\n-")}"
+      end
+    end
+  end
+end

data/lib/code_ownership/private/team_finder.rb

@@ -12,8 +12,8 @@ module CodeOwnership
 
       requires_ancestor { Kernel }
 
-      sig { params(file_path: String).returns(T.nilable(CodeTeams::Team)) }
-      def for_file(file_path)
+      sig { params(file_path: String, allow_raise: T::Boolean).returns(T.nilable(CodeTeams::Team)) }
+      def for_file(file_path, allow_raise: false)
         return nil if file_path.start_with?('./')
 
         return FilePathTeamCache.get(file_path) if FilePathTeamCache.cached?(file_path)
@@ -24,12 +24,22 @@ module CodeOwnership
         if result[:team_name].nil?
           FilePathTeamCache.set(file_path, nil)
         else
-          FilePathTeamCache.set(file_path, T.let(find_team!(T.must(result[:team_name])), T.nilable(CodeTeams::Team)))
+          FilePathTeamCache.set(file_path, T.let(find_team!(T.must(result[:team_name]), allow_raise: allow_raise), T.nilable(CodeTeams::Team)))
         end
 
         FilePathTeamCache.get(file_path)
       end
 
+      sig { params(files: T::Array[String], allow_raise: T::Boolean).returns(T::Hash[String, T.nilable(CodeTeams::Team)]) }
+      def teams_for_files(files, allow_raise: false)
+        ::RustCodeOwners.teams_for_files(files).each_with_object({}) do |path_team, hash|
+          file_path, team = path_team
+          found_team = team ? find_team!(team[:team_name], allow_raise: allow_raise) : nil
+          FilePathTeamCache.set(file_path, found_team)
+          hash[file_path] = found_team
+        end
+      end
+
       sig { params(klass: T.nilable(T.any(T::Class[T.anything], Module))).returns(T.nilable(::CodeTeams::Team)) }
       def for_class(klass)
         file_path = FilePathFinder.path_from_klass(klass)
@@ -43,7 +53,7 @@ module CodeOwnership
         owner_name = package.raw_hash['owner'] || package.metadata['owner']
         return nil if owner_name.nil?
 
-        find_team!(owner_name)
+        find_team!(owner_name, allow_raise: true)
       end
 
       sig { params(backtrace: T.nilable(T::Array[String]), excluded_teams: T::Array[::CodeTeams::Team]).returns(T.nilable(::CodeTeams::Team)) }
@@ -63,10 +73,14 @@ module CodeOwnership
         nil
       end
 
-      sig { params(team_name: String).returns(CodeTeams::Team) }
-      def find_team!(team_name)
-        CodeTeams.find(team_name) ||
+      sig { params(team_name: String, allow_raise: T::Boolean).returns(T.nilable(CodeTeams::Team)) }
+      def find_team!(team_name, allow_raise: false)
+        team = CodeTeams.find(team_name)
+        if team.nil? && allow_raise
           raise(StandardError, "Could not find team with name: `#{team_name}`. Make sure the team is one of `#{CodeTeams.all.map(&:name).sort}`")
+        end
+
+        team
       end
 
       private_class_method(:find_team!)

data/lib/code_ownership/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module CodeOwnership
-  VERSION = '2.0.0-1'
+  VERSION = '2.0.0-3'
 end

data/lib/code_ownership.rb

@@ -11,6 +11,7 @@ require 'code_ownership/version'
 require 'code_ownership/private/file_path_finder'
 require 'code_ownership/private/file_path_team_cache'
 require 'code_ownership/private/team_finder'
+require 'code_ownership/private/for_file_output_builder'
 require 'code_ownership/cli'
 
 begin
@@ -33,15 +34,135 @@ module CodeOwnership
   requires_ancestor { Kernel }
   GlobsToOwningTeamMap = T.type_alias { T::Hash[String, CodeTeams::Team] }
 
+  # Returns the version of the code_ownership gem and the codeowners-rs gem.
   sig { returns(T::Array[String]) }
   def version
     ["code_ownership version: #{VERSION}",
      "codeowners-rs version: #{::RustCodeOwners.version}"]
   end
 
-  sig { params(file: String).returns(T.nilable(CodeTeams::Team)) }
-  def for_file(file)
-    Private::TeamFinder.for_file(file)
+  # Returns the owning team for a given file path.
+  #
+  # @param file [String] The path to the file to find ownership for. Can be relative or absolute.
+  # @param from_codeowners [Boolean] (default: true) When true, uses CODEOWNERS file to determine ownership.
+  #                                  When false, uses alternative team finding strategies (e.g., package ownership).
+  #                                  from_codeowners true is faster because it simply matches the provided file to the generate CODEOWNERS file. This is a safe option when you can trust the CODEOWNERS file to be up to date.
+  # @param allow_raise [Boolean] (default: false) When true, raises an exception if ownership cannot be determined.
+  #                              When false, returns nil for files without ownership.
+  #
+  # @return [CodeTeams::Team, nil] The team that owns the file, or nil if no owner is found
+  #                                 (unless allow_raise is true, in which case an exception is raised).
+  #
+  # @example Find owner for a file using CODEOWNERS
+  #   team = CodeOwnership.for_file('app/models/user.rb')
+  #   # => #<CodeTeams::Team:0x... @name="platform">
+  #
+  # @example Find owner without using CODEOWNERS
+  #   team = CodeOwnership.for_file('app/models/user.rb', from_codeowners: false)
+  #   # => #<CodeTeams::Team:0x... @name="platform">
+  #
+  # @example Raise if no owner is found
+  #   team = CodeOwnership.for_file('unknown_file.rb', allow_raise: true)
+  #   # => raises exception if no owner found
+  #
+  sig { params(file: String, from_codeowners: T::Boolean, allow_raise: T::Boolean).returns(T.nilable(CodeTeams::Team)) }
+  def for_file(file, from_codeowners: true, allow_raise: false)
+    if from_codeowners
+      teams_for_files_from_codeowners([file], allow_raise: allow_raise).values.first
+    else
+      Private::TeamFinder.for_file(file, allow_raise: allow_raise)
+    end
+  end
+
+  # Returns the owning teams for multiple file paths using the CODEOWNERS file.
+  #
+  # This method efficiently determines ownership for multiple files in a single operation
+  # by leveraging the generated CODEOWNERS file. It's more performant than calling
+  # `for_file` multiple times when you need to check ownership for many files.
+  #
+  # @param files [Array<String>] An array of file paths to find ownership for.
+  #                               Paths can be relative to the project root or absolute.
+  # @param allow_raise [Boolean] (default: false) When true, raises an exception if a team
+  #                              name in CODEOWNERS cannot be resolved to an actual team.
+  #                              When false, returns nil for files with unresolvable teams.
+  #
+  # @return [T::Hash[String, T.nilable(CodeTeams::Team)]] A hash mapping each file path to its
+  #                                                 owning team. Files without ownership
+  #                                                 or with unresolvable teams will map to nil.
+  #
+  # @example Get owners for multiple files
+  #   files = ['app/models/user.rb', 'app/controllers/users_controller.rb', 'config/routes.rb']
+  #   owners = CodeOwnership.teams_for_files_from_codeowners(files)
+  #   # => {
+  #   #   'app/models/user.rb' => #<CodeTeams::Team:0x... @name="platform">,
+  #   #   'app/controllers/users_controller.rb' => #<CodeTeams::Team:0x... @name="platform">,
+  #   #   'config/routes.rb' => #<CodeTeams::Team:0x... @name="infrastructure">
+  #   # }
+  #
+  # @example Handle files without owners
+  #   files = ['owned_file.rb', 'unowned_file.txt']
+  #   owners = CodeOwnership.teams_for_files_from_codeowners(files)
+  #   # => {
+  #   #   'owned_file.rb' => #<CodeTeams::Team:0x... @name="backend">,
+  #   #   'unowned_file.txt' => nil
+  #   # }
+  #
+  # @note This method uses caching internally for performance. The cache is populated
+  #       as files are processed and reused for subsequent lookups.
+  #
+  # @note This method relies on the CODEOWNERS file being up-to-date. Run
+  #       `CodeOwnership.validate!` to ensure the CODEOWNERS file is current.
+  #
+  # @see #for_file for single file ownership lookup
+  # @see #validate! for ensuring CODEOWNERS file is up-to-date
+  #
+  sig { params(files: T::Array[String], allow_raise: T::Boolean).returns(T::Hash[String, T.nilable(CodeTeams::Team)]) }
+  def teams_for_files_from_codeowners(files, allow_raise: false)
+    Private::TeamFinder.teams_for_files(files, allow_raise: allow_raise)
+  end
+
+  # Returns detailed ownership information for a given file path.
+  #
+  # This method provides verbose ownership details including the team name,
+  # team configuration file path, and the reasons/sources for ownership assignment.
+  # It's particularly useful for debugging ownership assignments and understanding
+  # why a file is owned by a specific team.
+  #
+  # @param file [String] The path to the file to find ownership for. Can be relative or absolute.
+  #
+  # @return [T::Hash[Symbol, String], nil] A hash containing detailed ownership information,
+  #                                         or nil if no owner is found.
+  #
+  # The returned hash contains the following keys when an owner is found:
+  # - :team_name [String] - The name of the owning team
+  # - :team_config_yml [String] - Path to the team's configuration YAML file
+  # - :reasons [Array<String>] - List of reasons/sources explaining why this team owns the file
+  #                               (e.g., "CODEOWNERS pattern: /app/models/**", "Package ownership")
+  #
+  # @example Get verbose ownership details
+  #   details = CodeOwnership.for_file_verbose('app/models/user.rb')
+  #   # => {
+  #   #   team_name: "platform",
+  #   #   team_config_yml: "config/teams/platform.yml",
+  #   #   reasons: ["Matched pattern '/app/models/**' in CODEOWNERS"]
+  #   # }
+  #
+  # @example Handle unowned files
+  #   details = CodeOwnership.for_file_verbose('unowned_file.txt')
+  #   # => nil
+  #
+  # @note This method is primarily used by the CLI tool when the --verbose flag is provided,
+  #       allowing users to understand the ownership assignment logic.
+  #
+  # @note Unlike `for_file`, this method always uses the CODEOWNERS file and other ownership
+  #       sources to determine ownership, providing complete context about the ownership decision.
+  #
+  # @see #for_file for a simpler ownership lookup that returns just the team
+  # @see CLI#for_file for the command-line interface that uses this method
+  #
+  sig { params(file: String).returns(T.nilable(T::Hash[Symbol, String])) }
+  def for_file_verbose(file)
+    ::RustCodeOwners.for_file(file)
   end
 
   sig { params(team: T.any(CodeTeams::Team, String)).returns(T::Array[String]) }
@@ -50,9 +171,55 @@ module CodeOwnership
     ::RustCodeOwners.for_team(team.name)
   end
 
-  class InvalidCodeOwnershipConfigurationError < StandardError
-  end
-
+  # Validates code ownership configuration and optionally corrects issues.
+  #
+  # This method performs comprehensive validation of the code ownership setup, ensuring:
+  # 1. Only one ownership mechanism is defined per file (no conflicts between annotations, packages, or globs)
+  # 2. All referenced teams are valid (exist in CodeTeams configuration)
+  # 3. All files have ownership (unless explicitly listed in unowned_globs)
+  # 4. The .github/CODEOWNERS file is up-to-date and properly formatted
+  #
+  # When autocorrect is enabled, the method will automatically:
+  # - Generate or update the CODEOWNERS file based on current ownership rules
+  # - Fix any formatting issues in the CODEOWNERS file
+  # - Stage the corrected CODEOWNERS file (unless stage_changes is false)
+  #
+  # @param autocorrect [Boolean] Whether to automatically fix correctable issues (default: true)
+  #                              When true, regenerates and updates the CODEOWNERS file
+  #                              When false, only validates without making changes
+  #
+  # @param stage_changes [Boolean] Whether to stage the CODEOWNERS file after autocorrection (default: true)
+  #                                Only applies when autocorrect is true
+  #                                When false, changes are written but not staged with git
+  #
+  # @param files [Array<String>, nil] Ignored. This is a legacy parameter that is no longer used.
+  #
+  # @return [void]
+  #
+  # @raise [RuntimeError] Raises an error if validation fails with details about:
+  #                       - Files with conflicting ownership definitions
+  #                       - References to non-existent teams
+  #                       - Files without ownership (not in unowned_globs)
+  #                       - CODEOWNERS file inconsistencies
+  #
+  # @example Basic validation with autocorrection
+  #   CodeOwnership.validate!
+  #   # Validates all files and auto-corrects/stages CODEOWNERS if needed
+  #
+  # @example Validation without making changes
+  #   CodeOwnership.validate!(autocorrect: false)
+  #   # Only checks for issues without updating CODEOWNERS
+  #
+  # @example Validate and fix but don't stage changes
+  #   CodeOwnership.validate!(autocorrect: true, stage_changes: false)
+  #   # Fixes CODEOWNERS but doesn't stage it with git
+  #
+  # @note This method is called by the CLI command: bin/codeownership validate
+  # @note The validation can be disabled for CODEOWNERS by setting skip_codeowners_validation: true in config/code_ownership.yml
+  #
+  # @see CLI.validate! for the command-line interface
+  # @see https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners for CODEOWNERS format
+  #
   sig do
     params(
       autocorrect: T::Boolean,

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: code_ownership
 version: !ruby/object:Gem::Version
-  version: 2.0.0.pre.1
+  version: 2.0.0.pre.3
 platform: arm64-darwin
 authors:
 - Gusto Engineers
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2025-08-14 00:00:00.000000000 Z
+date: 2025-09-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: code_teams
@@ -181,6 +181,7 @@ files:
 - lib/code_ownership/cli.rb
 - lib/code_ownership/private/file_path_finder.rb
 - lib/code_ownership/private/file_path_team_cache.rb
+- lib/code_ownership/private/for_file_output_builder.rb
 - lib/code_ownership/private/permit_pack_owner_top_level_key.rb
 - lib/code_ownership/private/team_finder.rb
 - lib/code_ownership/version.rb