code_ownership 2.1.1-aarch64-mingw-ucrt

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 440e5064df89e8f6030e33c5b990262162d66e9395afa404836c88c1a6a74593
+  data.tar.gz: '08d7c9d42d3bb443d764f719910c7b7d31e1587d30c489f89ab36cde6d6d15da'
+SHA512:
+  metadata.gz: ffa68ab47c952d5a8d8f7625a9996392d64aced0bfa00a36db1747b0ee4ec7606b09dc68272ef6ff7a1ce31f294184a87e03317a89559272676ed28a11cadfb5
+  data.tar.gz: 9dd957f2c966baef82e9af05ffe84f5c3118758f824c14379e2e471393de491b7f192dd1c5854fce9cdd78391e931f50eb8ab5eab094a3c541eee4e356fd0f28

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Gusto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,237 @@
+# CodeOwnership
+
+This gem helps engineering teams declare ownership of code. This gem works best in large, usually monolithic code bases where many teams work together.
+
+Check out [`lib/code_ownership.rb`](https://github.com/rubyatscale/code_ownership/blob/main/lib/code_ownership.rb) to see the public API.
+
+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](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.
+
+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}'
+js_package_paths: []
+unowned_globs:
+  - db/**/*
+  - app/services/some_file1.rb
+  - app/services/some_file2.rb
+  - frontend/javascripts/**/__generated__/**/*
+```
+
+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.
+
+## 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.
+
+```
+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:
+
+```yml
+enforce_dependency: true
+enforce_privacy: true
+metadata:
+  owner: Team
+```
+
+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.
+
+### 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:
+  - app/services/stuff_belonging_to_my_team/**/**
+  - app/controllers/other_stuff_belonging_to_my_team/**/**
+unowned_globs:
+  - app/controllers/other_stuff_belonging_to_my_team/that_one_weird_dir_we_dont_own/*
+```
+
+### 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:
+
+```json
+{
+  // other keys
+  "metadata": {
+    "owner": "My Team"
+  }
+  // other keys
+}
+```
+
+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.
+
+> [!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.
+
+```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
+CodeOwnership.for_file('path/to/file/relative/to/application/root.rb')
+```
+
+Contributor note: If you are making updates to this method or the methods getting used here, please benchmark the performance of the new implementation against the current for both `for_files` and `for_file` (with 1, 100, 1000 files).
+
+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
+CodeOwnership.for_backtrace(exception.backtrace)
+```
+
+This will go through the backtrace, and return the first found owner of the files associated with frames within the backtrace.
+
+See `code_ownership_spec.rb` for an example.
+
+### `for_class`
+
+`CodeOwnership.for_class` can be given a class and will either return `nil`, or a `CodeTeams::Team`.
+
+```ruby
+CodeOwnership.for_class(MyClass)
+```
+
+Under the hood, this finds the file where the class is defined and returns the owner of that file.
+
+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:
+
+```
+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 `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`.
+
+## Proper Configuration & Validation
+
+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.
+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}'
+unowned_globs:
+  - db/**/*
+  - app/services/some_file1.rb
+  - app/services/some_file2.rb
+  - frontend/javascripts/**/__generated__/**/*
+```
+
+You can call the validation function with the Ruby API
+
+```ruby
+CodeOwnership.validate!
+```
+
+or the CLI
+
+```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.
+
+## 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/bin/codeownership

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+# typed: strict
+
+require 'code_ownership'
+CodeOwnership::Cli.run!(ARGV)

data/lib/code_ownership/cli.rb

@@ -0,0 +1,149 @@
+# typed: true
+# frozen_string_literal: true
+
+require 'optparse'
+require 'pathname'
+require 'fileutils'
+
+module CodeOwnership
+  class Cli
+    EXECUTABLE = 'bin/codeownership'
+
+    def self.run!(argv)
+      command = argv.shift
+      if command == 'validate'
+        validate!(argv)
+      elsif command == 'for_file'
+        for_file(argv)
+      elsif command == 'for_team'
+        for_team(argv)
+      elsif command == 'version'
+        version
+      elsif [nil, 'help'].include?(command)
+        puts <<~USAGE
+          Usage: #{EXECUTABLE} <subcommand>
+
+          Subcommands:
+            validate - run all validations
+            for_file - find code ownership for a single file
+            for_team - find code ownership information for a team
+            help  - display help information about code_ownership
+        USAGE
+      else
+        puts "'#{command}' is not a code_ownership command. See `#{EXECUTABLE} help`."
+      end
+    end
+
+    def self.validate!(argv)
+      options = {}
+
+      parser = OptionParser.new do |opts|
+        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
+        end
+
+        opts.on('-d', '--diff', 'Only run validations with staged files') do
+          options[:diff] = true
+        end
+
+        opts.on('-s', '--skip-stage', 'Skips staging the CODEOWNERS file') do
+          options[:skip_stage] = true
+        end
+
+        opts.on('--help', 'Shows this prompt') do
+          puts opts
+          exit
+        end
+      end
+      args = parser.order!(argv)
+      parser.parse!(args)
+
+      # 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
+
+      CodeOwnership.validate!(
+        files: files,
+        autocorrect: !options[:skip_autocorrect],
+        stage_changes: !options[:skip_stage]
+      )
+    end
+
+    def self.version
+      puts CodeOwnership.version.join("\n")
+    end
+
+    # For now, this just returns team ownership
+    # Later, this could also return code ownership errors about that file.
+    def self.for_file(argv)
+      options = {}
+
+      # Long-term, we probably want to use something like `thor` so we don't have to implement logic
+      # like this. In the short-term, this is a simple way for us to use the built-in OptionParser
+      # while having an ergonomic CLI.
+      files = argv.reject { |arg| arg.start_with?('--') }
+
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: #{EXECUTABLE} for_file [options]"
+
+        opts.on('--json', 'Output as JSON') do
+          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
+        end
+      end
+      args = parser.order!(argv)
+      parser.parse!(args)
+
+      if files.count != 1
+        raise "Please pass in one file. Use `#{EXECUTABLE} for_file --help` for more info"
+      end
+
+      puts CodeOwnership::Private::ForFileOutputBuilder.build(file_path: files.first, json: !!options[:json], verbose: !!options[:verbose])
+    end
+
+    def self.for_team(argv)
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: #{EXECUTABLE} for_team 'Team Name'"
+
+        opts.on('--help', 'Shows this prompt') do
+          puts opts
+          exit
+        end
+      end
+      teams = argv.reject { |arg| arg.start_with?('--') }
+      args = parser.order!(argv)
+      parser.parse!(args)
+
+      if teams.count != 1
+        raise "Please pass in one team. Use `#{EXECUTABLE} for_team --help` for more info"
+      end
+
+      puts CodeOwnership.for_team(teams.first).join("\n")
+    end
+  end
+end

data/lib/code_ownership/private/file_path_finder.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+# typed: strict
+
+module CodeOwnership
+  module Private
+    module FilePathFinder
+      extend T::Sig
+
+      # 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], 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
+        end
+      rescue NameError
+        nil
+      end
+
+      sig { params(backtrace: T.nilable(T::Array[String])).returns(T::Enumerable[String]) }
+      def self.from_backtrace(backtrace)
+        return [] unless backtrace
+
+        # The pattern for a backtrace hasn't changed in forever and is considered
+        # stable: https://github.com/ruby/ruby/blob/trunk/vm_backtrace.c#L303-L317
+        #
+        # This pattern matches a line like the following:
+        #
+        #   ./app/controllers/some_controller.rb:43:in `block (3 levels) in create'
+        #
+        backtrace_line = if RUBY_VERSION >= '3.4.0'
+                           %r{\A(#{Pathname.pwd}/|\./)?
+                               (?<file>.+)       # Matches 'app/controllers/some_controller.rb'
+                               :
+                               (?<line>\d+)      # Matches '43'
+                               :in\s
+                               '(?<function>.*)' # Matches "`block (3 levels) in create'"
+                             \z}x
+                         else
+                           %r{\A(#{Pathname.pwd}/|\./)?
+                               (?<file>.+)       # Matches 'app/controllers/some_controller.rb'
+                               :
+                               (?<line>\d+)      # Matches '43'
+                               :in\s
+                               `(?<function>.*)' # Matches "`block (3 levels) in create'"
+                             \z}x
+                         end
+
+        backtrace.lazy.filter_map do |line|
+          match = line.match(backtrace_line)
+          next unless match
+
+          T.must(match[:file])
+        end
+      end
+    end
+  end
+end

data/lib/code_ownership/private/file_path_team_cache.rb

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

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/permit_pack_owner_top_level_key.rb

@@ -0,0 +1,23 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'packwerk'
+
+module CodeOwnership
+  module Private
+    class PackOwnershipValidator
+      extend T::Sig
+      include Packwerk::Validator
+
+      sig { override.params(package_set: Packwerk::PackageSet, configuration: Packwerk::Configuration).returns(Result) }
+      def call(package_set, configuration)
+        Result.new(ok: true)
+      end
+
+      sig { override.returns(T::Array[String]) }
+      def permitted_keys
+        %w[owner]
+      end
+    end
+  end
+end

data/lib/code_ownership/private/team_finder.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+# typed: strict
+
+module CodeOwnership
+  module Private
+    module TeamFinder
+      extend T::Sig
+
+      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?
+          FilePathTeamCache.set(file_path, nil)
+        else
+          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 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?
+
+        for_file(file_path)
+      end
+
+      sig { params(package: Packs::Pack).returns(T.nilable(::CodeTeams::Team)) }
+      def self.for_package(package)
+        owner_name = package.raw_hash['owner'] || package.metadata['owner']
+        return nil if owner_name.nil?
+
+        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 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 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)
+            return [team, file]
+          end
+        end
+
+        nil
+      end
+
+      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!)
+    end
+  end
+end

data/lib/code_ownership/version.rb

@@ -0,0 +1,6 @@
+# typed: strict
+# frozen_string_literal: true
+
+module CodeOwnership
+  VERSION = '2.1.1'
+end

data/lib/code_ownership.rb

@@ -0,0 +1,319 @@
+# frozen_string_literal: true
+# typed: strict
+
+require 'code_teams'
+require 'sorbet-runtime'
+require 'json'
+require 'packs-specification'
+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
+  RUBY_VERSION =~ /(\d+\.\d+)/
+  require "code_ownership/#{Regexp.last_match(1)}/code_ownership"
+rescue LoadError
+  require 'code_ownership/code_ownership'
+end
+
+if defined?(Packwerk)
+  require 'code_ownership/private/permit_pack_owner_top_level_key'
+end
+
+module CodeOwnership
+  extend T::Sig
+
+  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 self.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 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 self.for_team(team)
+    team = T.must(CodeTeams.find(team)) if team.is_a?(String)
+    ::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,
+      stage_changes: T::Boolean,
+      files: T.nilable(T::Array[String])
+    ).void
+  end
+  def self.validate!(
+    autocorrect: true,
+    stage_changes: true,
+    files: nil
+  )
+    if autocorrect
+      ::RustCodeOwners.generate_and_validate(files, !stage_changes)
+    else
+      ::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 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 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], 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 self.for_package(package)
+    Private::TeamFinder.for_package(package)
+  end
+
+  # Generally, you should not ever need to do this, because once your ruby process loads, cached content should not change.
+  # Namely, the set of files, packages, and directories which are tracked for ownership should not change.
+  # The primary reason this is helpful is for clients of CodeOwnership who want to test their code, and each test context
+  # has different ownership and tracked files.
+  sig { void }
+  def self.bust_caches!
+    Private::FilePathTeamCache.bust_cache!
+  end
+end

metadata

@@ -0,0 +1,219 @@
+--- !ruby/object:Gem::Specification
+name: code_ownership
+version: !ruby/object:Gem::Version
+  version: 2.1.1
+platform: aarch64-mingw-ucrt
+authors:
+- Gusto Engineers
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-01-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: code_teams
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: packs-specification
+  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: sorbet-runtime
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.6.12763
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.6.12763
+- !ruby/object:Gem::Dependency
+  name: debug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: packwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sorbet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: tapioca
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A gem to help engineering teams declare ownership of code
+email:
+- dev@gusto.com
+executables:
+- codeownership
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- bin/codeownership
+- lib/code_ownership.rb
+- 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
+homepage: https://github.com/rubyatscale/code_ownership
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/rubyatscale/code_ownership
+  source_code_uri: https://github.com/rubyatscale/code_ownership
+  changelog_uri: https://github.com/rubyatscale/code_ownership/releases
+  allowed_push_host: https://rubygems.org
+  cargo_crate_name: code_ownership
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: 4.1.dev
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.23
+signing_key: 
+specification_version: 4
+summary: A gem to help engineering teams declare ownership of code
+test_files: []