code_ownership 2.0.0.pre.1-x64-mingw-ucrt → 2.1.3-x64-mingw-ucrt

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3184eb314ac8d7a612bc93f7e2f10d3920773830601ee6c94792e4ce809b3c5b
-  data.tar.gz: 9974b2ba6b5a755476f47efe93988c7b4bc69b875064c02c3d16461c110852ae
+  metadata.gz: 824cabc8c0760c992bffd8bc1410a220f92aecd86f95ab5653fb1cfb7b282ef1
+  data.tar.gz: 14d955eee3158c0edf56da3f8ae3da0a4f8620d7012b52d37696510ae7f0f56a
 SHA512:
-  metadata.gz: aa4eeed10aae508939d1f001f7db0b5ae3c3c186232f896e525fee1caa940127fa97b9a0062ee84881912258133d369e470598c57c29e3586cc8ae20c4e301a6
-  data.tar.gz: 8c8409aa9de19a3849ed2f507c741b4cf70ba1d7a4f6a67c1af675b29cd85c657c1e7a7b8a851a12477db3421db2d3678f8fd0e0ad531a75c29395f521781335
+  metadata.gz: deebbcf22becdb436b047f2551b3a12f3664f2410ea1dd9269391c252fb22ce25745245a13985d257b64294755f199747283d05b6abf125b953547e6fab8d99b
+  data.tar.gz: 3947a41c61ab114aa5f79e9a4178a85d1d02f18a65a64faf29ed3dc7971cfd3181f73e7962e3970808c1acfbf681f9ff6f6745df509361a8e370dbbc4f4886e4

data/README.md

@@ -6,13 +6,14 @@ Check out [`lib/code_ownership.rb`](https://github.com/rubyatscale/code_ownershi
 
 Check out [`code_ownership_spec.rb`](https://github.com/rubyatscale/code_ownership/blob/main/spec/lib/code_ownership_spec.rb) to see examples of how code ownership is used.
 
-There is also a [companion VSCode Extension]([url](https://github.com/rubyatscale/code-ownership-vscode)) for this gem. Just search `Gusto.code-ownership-vscode` in the VSCode Extension Marketplace.
+There is also a [companion VSCode Extension](https://github.com/rubyatscale/code-ownership-vscode) for this gem. Just search `Gusto.code-ownership-vscode` in the VSCode Extension Marketplace.
 
 ## Getting started
 
-To get started there's a few things you should do.
+To get started there are a few things you should do.
+
+1. Create a `config/code_ownership.yml` file and declare where your files live. Here's a sample to start with:
 
-1) Create a `config/code_ownership.yml` file and declare where your files live. Here's a sample to start with:
 ```yml
 owned_globs:
   - '{app,components,config,frontend,lib,packs,spec}/**/*.{rb,rake,js,jsx,ts,tsx}'
@@ -23,33 +24,42 @@ unowned_globs:
   - app/services/some_file2.rb
   - frontend/javascripts/**/__generated__/**/*
 ```
-2) Declare some teams. Here's an example, that would live at `config/teams/operations.yml`:
+
+2. Declare some teams. Here's an example, that would live at `config/teams/operations.yml`:
+
 ```yml
 name: Operations
 github:
   team: '@my-org/operations-team'
 ```
-3) Declare ownership. You can do this at a directory level or at a file level. All of the files within the `owned_globs` you declared in step 1 will need to have an owner assigned (or be opted out via `unowned_globs`). See the next section for more detail.
-4) Run validations when you commit, and/or in CI. If you run validations in CI, ensure that if your `.github/CODEOWNERS` file gets changed, that gets pushed to the PR.
+
+3. Declare ownership. You can do this at a directory level or at a file level. All of the files within the `owned_globs` you declared in step 1 will need to have an owner assigned (or be opted out via `unowned_globs`). See the next section for more detail.
+4. Run validations when you commit, and/or in CI. If you run validations in CI, ensure that if your `.github/CODEOWNERS` file gets changed, that gets pushed to the PR.
 
 ## Usage: Declaring Ownership
 
 There are five ways to declare code ownership using this gem:
 
 ### Directory-Based Ownership
-Directory based ownership allows for all files in that directory and all its sub-directories to be owned by one team. To define this, add a `.codeowner` file inside that directory with the name of the team as the contents of that file.
+
+Directory-based ownership allows for all files in that directory and all its sub-directories to be owned by one team. To define this, add a `.codeowner` file inside that directory with the name of the team as the contents of that file.
+
 ```
 Team
 ```
 
 ### File-Annotation Based Ownership
+
 File annotations are a last resort if there is no clear home for your code. File annotations go at the top of your file, and look like this:
+
 ```ruby
 # @team MyTeam
 ```
 
 ### Package-Based Ownership
-Package based ownership integrates [`packwerk`](https://github.com/Shopify/packwerk) and has ownership defined per package. To define that all files within a package are owned by one team, configure your `package.yml` like this:
+
+Package-based ownership integrates [`packwerk`](https://github.com/Shopify/packwerk) and has ownership defined per package. To define that all files within a package are owned by one team, configure your `package.yml` like this:
+
 ```yml
 enforce_dependency: true
 enforce_privacy: true
@@ -58,16 +68,19 @@ metadata:
 ```
 
 You can also define `owner` as a top-level key, e.g.
+
 ```yml
 enforce_dependency: true
 enforce_privacy: true
 owner: Team
 ```
 
-To do this, add `code_ownership` to the `require` key of your `packwerk.yml`. See https://github.com/Shopify/packwerk/blob/main/USAGE.md#loading-extensions for more information.
+To do this, add `code_ownership` to the `require` key of your `packwerk.yml`. See <https://github.com/Shopify/packwerk/blob/main/USAGE.md#loading-extensions> for more information.
 
 ### Glob-Based Ownership
+
 In your team's configured YML (see [`code_teams`](https://github.com/rubyatscale/code_teams)), you can set `owned_globs` to be a glob of files your team owns. For example, in `my_team.yml`:
+
 ```yml
 name: My Team
 owned_globs:
@@ -78,7 +91,8 @@ unowned_globs:
 ```
 
 ### Javascript Package Ownership
-Javascript package based ownership allows you to specify an ownership key in a `package.json`. To use this, configure your `package.json` like this:
+
+JavaScript package-based ownership allows you to specify an ownership key in a `package.json`. To use this, configure your `package.json` like this:
 
 ```json
 {
@@ -91,22 +105,26 @@ Javascript package based ownership allows you to specify an ownership key in a `
 ```
 
 You can also tell `code_ownership` where to find JS packages in the configuration, like this:
+
 ```yml
 js_package_paths:
   - frontend/javascripts/packages/*
   - frontend/other_location_for_packages/*
 ```
 
-This defaults `**/`, which makes it look for `package.json` files across your application.
+This defaults to `**/`, which makes it look for `package.json` files across your application.
 
 > [!NOTE]
-> Javscript package ownership does not respect `unowned_globs`. If you wish to disable usage of this feature you can set `js_package_paths` to an empty list.
+> JavaScript package ownership does not respect `unowned_globs`. If you wish to disable usage of this feature you can set `js_package_paths` to an empty list.
+
 ```yml
 js_package_paths: []
 ```
 
 ## Usage: Reading CodeOwnership
+
 ### `for_file`
+
 `CodeOwnership.for_file`, given a relative path to a file returns a `CodeTeams::Team` if there is a team that owns the file, `nil` otherwise.
 
 ```ruby
@@ -118,6 +136,7 @@ Contributor note: If you are making updates to this method or the methods gettin
 See `code_ownership_spec.rb` for examples.
 
 ### `for_backtrace`
+
 `CodeOwnership.for_backtrace` can be given a backtrace and will either return `nil`, or a `CodeTeams::Team`.
 
 ```ruby
@@ -141,19 +160,22 @@ Under the hood, this finds the file where the class is defined and returns the o
 See `code_ownership_spec.rb` for an example.
 
 ### `for_team`
+
 `CodeOwnership.for_team` can be used to generate an ownership report for a team.
+
 ```ruby
 CodeOwnership.for_team('My Team')
 ```
 
 You can shovel this into a markdown file for easy viewing using the CLI:
+
 ```
-bin/codeownership for_team 'My Team' > tmp/ownership_report.md
+codeownership for_team 'My Team' > tmp/ownership_report.md
 ```
 
 ## Usage: Generating a `CODEOWNERS` file
 
-A `CODEOWNERS` file defines who owns specific files or paths in a repository. When you run `bin/codeownership validate`, a `.github/CODEOWNERS` file will automatically be generated and updated.
+A `CODEOWNERS` file defines who owns specific files or paths in a repository. When you run `codeownership validate`, a `.github/CODEOWNERS` file will automatically be generated and updated.
 
 If `codeowners_path` is set in `code_ownership.yml` codeowners will use that path to generate the `CODEOWNERS` file. For example, `codeowners_path: docs` will generate `docs/CODEOWNERS`.
 
@@ -161,14 +183,15 @@ If `codeowners_path` is set in `code_ownership.yml` codeowners will use that pat
 
 CodeOwnership comes with a validation function to ensure the following things are true:
 
-1) Only one mechanism is defining file ownership. That is -- you can't have a file annotation on a file owned via package-based or glob-based ownership. This helps make ownership behavior more clear by avoiding concerns about precedence.
-2) All teams referenced as an owner for any file or package is a valid team (i.e. it's in the list of `CodeTeams.all`).
-3) All files have ownership. You can specify in `unowned_globs` to represent a TODO list of files to add ownership to.
-3) The `.github/CODEOWNERS` file is up to date. This is automatically corrected and staged unless specified otherwise with `bin/codeownership validate --skip-autocorrect --skip-stage`. You can turn this validation off by setting `skip_codeowners_validation: true` in `config/code_ownership.yml`.
+1. Only one mechanism is defining file ownership. That is -- you can't have a file annotation on a file owned via package-based or glob-based ownership. This helps make ownership behavior more clear by avoiding concerns about precedence.
+2. All teams referenced as an owner for any file or package are valid teams (i.e. they're in the list of `CodeTeams.all`).
+3. All files have ownership. You can specify in `unowned_globs` to represent a TODO list of files to add ownership to.
+4. The `.github/CODEOWNERS` file is up to date. This is automatically corrected and staged unless specified otherwise with `bin/codeownership validate --skip-autocorrect --skip-stage`. You can turn this validation off by setting `skip_codeowners_validation: true` in `config/code_ownership.yml`.
 
 CodeOwnership also allows you to specify which globs and file extensions should be considered ownable.
 
 Here is an example `config/code_ownership.yml`.
+
 ```yml
 owned_globs:
   - '{app,components,config,frontend,lib,packs,spec}/**/*.{rb,rake,js,jsx,ts,tsx}'
@@ -178,24 +201,37 @@ unowned_globs:
   - app/services/some_file2.rb
   - frontend/javascripts/**/__generated__/**/*
 ```
+
 You can call the validation function with the Ruby API
+
 ```ruby
 CodeOwnership.validate!
 ```
+
 or the CLI
-```
-bin/codeownership validate
+
+```bash
+# Validate all files
+codeownership validate
+
+# Validate specific files
+codeownership validate path/to/file1.rb path/to/file2.rb
+
+# Validate only staged files
+codeownership validate --diff
 ```
 
 ## Development
 
-Please add to `CHANGELOG.md` and this `README.md` when you make make changes.
+Please add to `CHANGELOG.md` and this `README.md` when you make changes.
 
 ## Running specs
+
 ```sh
 bundle install
 bundle exec rake
 ```
 
 ## Creating a new release
+
 Simply [create a new release](https://github.com/rubyatscale/code_ownership/releases/new) with github. The release tag must match the gem version

data/lib/code_ownership/cli.rb

@@ -1,4 +1,5 @@
 # typed: true
+# frozen_string_literal: true
 
 require 'optparse'
 require 'pathname'
@@ -37,7 +38,7 @@ module CodeOwnership
       options = {}
 
       parser = OptionParser.new do |opts|
-        opts.banner = "Usage: #{EXECUTABLE} validate [options]"
+        opts.banner = "Usage: #{EXECUTABLE} validate [options] [files...]"
 
         opts.on('--skip-autocorrect', 'Skip automatically correcting any errors, such as the .github/CODEOWNERS file') do
           options[:skip_autocorrect] = true
@@ -59,11 +60,22 @@ module CodeOwnership
       args = parser.order!(argv)
       parser.parse!(args)
 
-      files = if options[:diff]
+      # Collect any remaining arguments as file paths
+      specified_files = argv.reject { |arg| arg.start_with?('--') }
+
+      files = if !specified_files.empty?
+                # Files explicitly provided on command line
+                if options[:diff]
+                  warn 'Warning: Ignoring --diff flag because explicit files were provided'
+                end
+                specified_files.select { |file| File.exist?(file) }
+              elsif options[:diff]
+                # Staged files from git
                 ENV.fetch('CODEOWNERS_GIT_STAGED_FILES') { `git diff --staged --name-only` }.split("\n").select do |file|
                   File.exist?(file)
                 end
               else
+                # No files specified, validate all
                 nil
               end
 
@@ -95,6 +107,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 +123,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/file_path_finder.rb

@@ -1,29 +1,41 @@
 # frozen_string_literal: true
-
 # typed: strict
 
 module CodeOwnership
   module Private
     module FilePathFinder
-      module_function
-
       extend T::Sig
-      extend T::Helpers
+
+      sig { returns(String) }
+      def self.pwd_prefix
+        @pwd_prefix ||= T.let("#{Dir.pwd}/", T.nilable(String))
+      end
+
+      sig { returns(Pathname) }
+      def self.pwd
+        @pwd ||= T.let(Pathname.pwd, T.nilable(Pathname))
+      end
 
       # Returns a string version of the relative path to a Rails constant,
       # or nil if it can't find anything
-      sig { params(klass: T.nilable(T.any(T::Class[T.anything], Module))).returns(T.nilable(String)) }
-      def path_from_klass(klass)
+      sig { params(klass: T.nilable(T.any(T::Class[T.anything], T::Module[T.anything]))).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
+          return nil unless path
+
+          if path.start_with?(pwd_prefix)
+            path.delete_prefix(pwd_prefix)
+          else
+            Pathname.new(path).relative_path_from(pwd).to_s
+          end
         end
       rescue NameError
         nil
       end
 
       sig { params(backtrace: T.nilable(T::Array[String])).returns(T::Enumerable[String]) }
-      def from_backtrace(backtrace)
+      def self.from_backtrace(backtrace)
         return [] unless backtrace
 
         # The pattern for a backtrace hasn't changed in forever and is considered
@@ -34,7 +46,7 @@ module CodeOwnership
         #   ./app/controllers/some_controller.rb:43:in `block (3 levels) in create'
         #
         backtrace_line = if RUBY_VERSION >= '3.4.0'
-                           %r{\A(#{Pathname.pwd}/|\./)?
+                           %r{\A(#{pwd}/|\./)?
                                (?<file>.+)       # Matches 'app/controllers/some_controller.rb'
                                :
                                (?<line>\d+)      # Matches '43'
@@ -42,7 +54,7 @@ module CodeOwnership
                                '(?<function>.*)' # Matches "`block (3 levels) in create'"
                              \z}x
                          else
-                           %r{\A(#{Pathname.pwd}/|\./)?
+                           %r{\A(#{pwd}/|\./)?
                                (?<file>.+)       # Matches 'app/controllers/some_controller.rb'
                                :
                                (?<line>\d+)      # Matches '43'

data/lib/code_ownership/private/file_path_team_cache.rb

@@ -1,37 +1,33 @@
 # frozen_string_literal: true
-
 # typed: strict
 
 module CodeOwnership
   module Private
     module FilePathTeamCache
-      module_function
-
       extend T::Sig
-      extend T::Helpers
 
       sig { params(file_path: String).returns(T.nilable(CodeTeams::Team)) }
-      def get(file_path)
+      def self.get(file_path)
         cache[file_path]
       end
 
       sig { params(file_path: String, team: T.nilable(CodeTeams::Team)).void }
-      def set(file_path, team)
+      def self.set(file_path, team)
         cache[file_path] = team
       end
 
       sig { params(file_path: String).returns(T::Boolean) }
-      def cached?(file_path)
+      def self.cached?(file_path)
         cache.key?(file_path)
       end
 
       sig { void }
-      def bust_cache!
+      def self.bust_cache!
         @cache = nil
       end
 
       sig { returns(T::Hash[String, T.nilable(CodeTeams::Team)]) }
-      def cache
+      def self.cache
         @cache ||= T.let(@cache,
           T.nilable(T::Hash[String, T.nilable(CodeTeams::Team)]))
         @cache ||= {}

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

@@ -1,37 +1,57 @@
 # frozen_string_literal: true
-
 # typed: strict
 
 module CodeOwnership
   module Private
     module TeamFinder
-      module_function
-
       extend T::Sig
-      extend T::Helpers
 
-      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 self.for_file(file_path, allow_raise: false)
         return nil if file_path.start_with?('./')
 
         return FilePathTeamCache.get(file_path) if FilePathTeamCache.cached?(file_path)
 
         result = T.let(RustCodeOwners.for_file(file_path), T.nilable(T::Hash[Symbol, String]))
-        return if result.nil?
 
-        if result[:team_name].nil?
+        if result.nil? || 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(klass: T.nilable(T.any(T::Class[T.anything], Module))).returns(T.nilable(::CodeTeams::Team)) }
-      def for_class(klass)
+      sig { params(files: T::Array[String], allow_raise: T::Boolean).returns(T::Hash[String, T.nilable(CodeTeams::Team)]) }
+      def self.teams_for_files(files, allow_raise: false)
+        result = {}
+
+        # Collect cached results and identify non-cached files
+        not_cached_files = []
+        files.each do |file_path|
+          if FilePathTeamCache.cached?(file_path)
+            result[file_path] = FilePathTeamCache.get(file_path)
+          else
+            not_cached_files << file_path
+          end
+        end
+
+        return result if not_cached_files.empty?
+
+        # Process non-cached files
+        ::RustCodeOwners.teams_for_files(not_cached_files).each do |path_team|
+          file_path, team = path_team
+          found_team = team ? find_team!(team[:team_name], allow_raise: allow_raise) : nil
+          FilePathTeamCache.set(file_path, found_team)
+          result[file_path] = found_team
+        end
+
+        result
+      end
+
+      sig { params(klass: T.nilable(T.any(T::Class[T.anything], T::Module[T.anything]))).returns(T.nilable(::CodeTeams::Team)) }
+      def self.for_class(klass)
         file_path = FilePathFinder.path_from_klass(klass)
         return nil if file_path.nil?
 
@@ -39,20 +59,20 @@ module CodeOwnership
       end
 
       sig { params(package: Packs::Pack).returns(T.nilable(::CodeTeams::Team)) }
-      def for_package(package)
+      def self.for_package(package)
         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)) }
-      def for_backtrace(backtrace, excluded_teams: [])
+      def self.for_backtrace(backtrace, excluded_teams: [])
         first_owned_file_for_backtrace(backtrace, excluded_teams: excluded_teams)&.first
       end
 
       sig { params(backtrace: T.nilable(T::Array[String]), excluded_teams: T::Array[::CodeTeams::Team]).returns(T.nilable([::CodeTeams::Team, String])) }
-      def first_owned_file_for_backtrace(backtrace, excluded_teams: [])
+      def self.first_owned_file_for_backtrace(backtrace, excluded_teams: [])
         FilePathFinder.from_backtrace(backtrace).each do |file|
           team = for_file(file)
           if team && !excluded_teams.include?(team)
@@ -63,10 +83,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 self.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,6 @@
+# typed: strict
 # frozen_string_literal: true
 
 module CodeOwnership
-  VERSION = '2.0.0-1'
+  VERSION = '2.1.3'
 end

data/lib/code_ownership.rb

@@ -1,8 +1,6 @@
 # frozen_string_literal: true
-
 # typed: strict
 
-require 'set'
 require 'code_teams'
 require 'sorbet-runtime'
 require 'json'
@@ -11,6 +9,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
@@ -25,34 +24,196 @@ if defined?(Packwerk)
 end
 
 module CodeOwnership
-  module_function
-
   extend T::Sig
-  extend T::Helpers
 
-  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
+  def self.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 self.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 self.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 self.for_file_verbose(file)
+    ::RustCodeOwners.for_file(file)
   end
 
   sig { params(team: T.any(CodeTeams::Team, String)).returns(T::Array[String]) }
-  def for_team(team)
+  def self.for_team(team)
     team = T.must(CodeTeams.find(team)) if team.is_a?(String)
     ::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,
@@ -60,39 +221,90 @@ module CodeOwnership
       files: T.nilable(T::Array[String])
     ).void
   end
-  def validate!(
+  def self.validate!(
     autocorrect: true,
     stage_changes: true,
     files: nil
   )
     if autocorrect
-      ::RustCodeOwners.generate_and_validate(!stage_changes)
+      ::RustCodeOwners.generate_and_validate(files, !stage_changes)
     else
-      ::RustCodeOwners.validate
+      ::RustCodeOwners.validate(files)
+    end
+  end
+
+  # Removes the file annotation (e.g., "# @team TeamName") from a file.
+  #
+  # This method removes the ownership annotation from the first line of a file,
+  # which is typically used to declare team ownership at the file level.
+  # The annotation can be in the form of:
+  # - Ruby comments: # @team TeamName
+  # - JavaScript/TypeScript comments: // @team TeamName
+  # - YAML comments: -# @team TeamName
+  #
+  # If the file does not have an annotation or the annotation doesn't match a valid team,
+  # this method does nothing.
+  #
+  # @param filename [String] The path to the file from which to remove the annotation.
+  #                          Can be relative or absolute.
+  #
+  # @return [void]
+  #
+  # @example Remove annotation from a Ruby file
+  #   # Before: File contains "# @team Platform\nclass User; end"
+  #   CodeOwnership.remove_file_annotation!('app/models/user.rb')
+  #   # After: File contains "class User; end"
+  #
+  # @example Remove annotation from a JavaScript file
+  #   # Before: File contains "// @team Frontend\nexport default function() {}"
+  #   CodeOwnership.remove_file_annotation!('app/javascript/component.js')
+  #   # After: File contains "export default function() {}"
+  #
+  # @note This method modifies the file in place.
+  # @note Leading newlines after the annotation are also removed to maintain clean formatting.
+  #
+  sig { params(filename: String).void }
+  def self.remove_file_annotation!(filename)
+    filepath = Pathname.new(filename)
+
+    begin
+      content = filepath.read
+    rescue Errno::EISDIR, Errno::ENOENT
+      # Ignore files that fail to read (directories, missing files, etc.)
+      return
     end
+
+    # Remove the team annotation and any trailing newlines after it
+    team_pattern = %r{\A(?:#|//|-#) @team .*\n+}
+    new_content = content.sub(team_pattern, '')
+
+    filepath.write(new_content) if new_content != content
+  rescue ArgumentError => e
+    # Handle invalid byte sequences gracefully
+    raise unless e.message.include?('invalid byte sequence')
   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[::CodeTeams::Team]).returns(T.nilable(::CodeTeams::Team)) }
-  def for_backtrace(backtrace, excluded_teams: [])
+  def self.for_backtrace(backtrace, excluded_teams: [])
     Private::TeamFinder.for_backtrace(backtrace, excluded_teams: excluded_teams)
   end
 
   # Given a backtrace from either `Exception#backtrace` or `caller`, find the
   # first owned file in it, useful for figuring out which file is being blamed.
   sig { params(backtrace: T.nilable(T::Array[String]), excluded_teams: T::Array[::CodeTeams::Team]).returns(T.nilable([::CodeTeams::Team, String])) }
-  def first_owned_file_for_backtrace(backtrace, excluded_teams: [])
+  def self.first_owned_file_for_backtrace(backtrace, excluded_teams: [])
     Private::TeamFinder.first_owned_file_for_backtrace(backtrace, excluded_teams: excluded_teams)
   end
 
-  sig { params(klass: T.nilable(T.any(T::Class[T.anything], Module))).returns(T.nilable(::CodeTeams::Team)) }
-  def for_class(klass)
+  sig { params(klass: T.nilable(T.any(T::Class[T.anything], T::Module[T.anything]))).returns(T.nilable(::CodeTeams::Team)) }
+  def self.for_class(klass)
     Private::TeamFinder.for_class(klass)
   end
 
   sig { params(package: Packs::Pack).returns(T.nilable(::CodeTeams::Team)) }
-  def for_package(package)
+  def self.for_package(package)
     Private::TeamFinder.for_package(package)
   end
 
@@ -103,5 +315,7 @@ module CodeOwnership
   sig { void }
   def self.bust_caches!
     Private::FilePathTeamCache.bust_cache!
+    Private::FilePathFinder.instance_variable_set(:@pwd, nil)
+    Private::FilePathFinder.instance_variable_set(:@pwd_prefix, nil)
   end
 end

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.1.3
 platform: x64-mingw-ucrt
 authors:
 - Gusto Engineers
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2025-08-14 00:00:00.000000000 Z
+date: 2026-06-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: code_teams
@@ -44,14 +44,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.5.11249
+        version: 0.6.12763
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.5.11249
+        version: 0.6.12763
 - !ruby/object:Gem::Dependency
   name: debug
   requirement: !ruby/object:Gem::Requirement
@@ -176,11 +176,13 @@ files:
 - README.md
 - bin/codeownership
 - lib/code_ownership.rb
-- lib/code_ownership/3.2/code_ownership.so
+- lib/code_ownership/3.3/code_ownership.so
 - lib/code_ownership/3.4/code_ownership.so
+- lib/code_ownership/4.0/code_ownership.so
 - 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
@@ -201,10 +203,10 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.2'
+      version: '3.3'
   - - "<"
     - !ruby/object:Gem::Version
-      version: 3.5.dev
+      version: 4.1.dev
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="