code_ownership 2.0.0.pre.1-x86_64-darwin

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fc4bf43044b38af02a0e58167575c930364561d5a0cfa1fd7f7de91406c21e24
+  data.tar.gz: 3874a52d8fc03a1edc7de7e5c8a9d48ef8ea012b7b7993e23a7107a88ca35c52
+SHA512:
+  metadata.gz: 98dd439775bb33f6efe3ee33925d0e8302078d8433cb5f2185bcbb58fa3f956efdc05ad403e14bd438f25270392e127b47a6d61f15de719fd6c4ff1ea1737e7e
+  data.tar.gz: 285db4ba1df6ae685b492c2110d6a0e919928972e356db0abc82e4bbb0d75dba0b04200aed3302d5dfb8d75d5738429dbbfaba5e2efa1d6d8ec0506e77a848e8

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,201 @@
+# 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]([url](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:
+```
+bin/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.
+
+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.
+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`.
+
+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
+```
+bin/codeownership validate
+```
+
+## 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,150 @@
+# typed: 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]"
+
+        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)
+
+      files = if options[:diff]
+                ENV.fetch('CODEOWNERS_GIT_STAGED_FILES') { `git diff --staged --name-only` }.split("\n").select do |file|
+                  File.exist?(file)
+                end
+              else
+                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('--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
+
+      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
+    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,63 @@
+# frozen_string_literal: true
+
+# typed: strict
+
+module CodeOwnership
+  module Private
+    module FilePathFinder
+      module_function
+
+      extend T::Sig
+      extend T::Helpers
+
+      # 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)
+        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 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,41 @@
+# 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)
+        cache[file_path]
+      end
+
+      sig { params(file_path: String, team: T.nilable(CodeTeams::Team)).void }
+      def set(file_path, team)
+        cache[file_path] = team
+      end
+
+      sig { params(file_path: String).returns(T::Boolean) }
+      def cached?(file_path)
+        cache.key?(file_path)
+      end
+
+      sig { void }
+      def bust_cache!
+        @cache = nil
+      end
+
+      sig { returns(T::Hash[String, T.nilable(CodeTeams::Team)]) }
+      def cache
+        @cache ||= T.let(@cache,
+          T.nilable(T::Hash[String, T.nilable(CodeTeams::Team)]))
+        @cache ||= {}
+      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,75 @@
+# 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)
+        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])), 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)
+        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 for_package(package)
+        owner_name = package.raw_hash['owner'] || package.metadata['owner']
+        return nil if owner_name.nil?
+
+        find_team!(owner_name)
+      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: [])
+        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: [])
+        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).returns(CodeTeams::Team) }
+      def find_team!(team_name)
+        CodeTeams.find(team_name) ||
+          raise(StandardError, "Could not find team with name: `#{team_name}`. Make sure the team is one of `#{CodeTeams.all.map(&:name).sort}`")
+      end
+
+      private_class_method(:find_team!)
+    end
+  end
+end

data/lib/code_ownership/version.rb

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

data/lib/code_ownership.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+# typed: strict
+
+require 'set'
+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/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
+  module_function
+
+  extend T::Sig
+  extend T::Helpers
+
+  requires_ancestor { Kernel }
+  GlobsToOwningTeamMap = T.type_alias { T::Hash[String, CodeTeams::Team] }
+
+  sig { returns(T::Array[String]) }
+  def version
+    ["code_ownership version: #{VERSION}",
+     "codeowners-rs version: #{::RustCodeOwners.version}"]
+  end
+
+  sig { params(file: String).returns(T.nilable(CodeTeams::Team)) }
+  def for_file(file)
+    Private::TeamFinder.for_file(file)
+  end
+
+  sig { params(team: T.any(CodeTeams::Team, String)).returns(T::Array[String]) }
+  def for_team(team)
+    team = T.must(CodeTeams.find(team)) if team.is_a?(String)
+    ::RustCodeOwners.for_team(team.name)
+  end
+
+  class InvalidCodeOwnershipConfigurationError < StandardError
+  end
+
+  sig do
+    params(
+      autocorrect: T::Boolean,
+      stage_changes: T::Boolean,
+      files: T.nilable(T::Array[String])
+    ).void
+  end
+  def validate!(
+    autocorrect: true,
+    stage_changes: true,
+    files: nil
+  )
+    if autocorrect
+      ::RustCodeOwners.generate_and_validate(!stage_changes)
+    else
+      ::RustCodeOwners.validate
+    end
+  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: [])
+    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: [])
+    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)
+    Private::TeamFinder.for_class(klass)
+  end
+
+  sig { params(package: Packs::Pack).returns(T.nilable(::CodeTeams::Team)) }
+  def 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,218 @@
+--- !ruby/object:Gem::Specification
+name: code_ownership
+version: !ruby/object:Gem::Version
+  version: 2.0.0.pre.1
+platform: x86_64-darwin
+authors:
+- Gusto Engineers
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2025-08-14 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.5.11249
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.5.11249
+- !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.2/code_ownership.bundle
+- lib/code_ownership/3.4/code_ownership.bundle
+- 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/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.2'
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: 3.5.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: []