updating code_ownership docs

Author: perryqh

lib/code_ownership.rb

@@ -34,12 +34,37 @@ 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
 
+  # 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
@@ -49,11 +74,92 @@ def for_file(file, from_codeowners: true, allow_raise: false)
     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)
@@ -65,6 +171,55 @@ def for_team(team)
     ::RustCodeOwners.for_team(team.name)
   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,