Add opt-in CodeTeams test helpers (#23)

* feat: add CodeTeams::Testing helpers

Adds an opt-in testing helper for creating in-memory teams and exposing them via
CodeTeams.all/find.

* feat: add RSpec helper integration

Provides an opt-in RSpec helper (code_team_with_config) and per-example cleanup
for in-memory teams.

* feat: make RSpecHelpers inclusion opt-in

Stop auto-including CodeTeams::RSpecHelpers; clients can include it in their own
RSpec config. The testing integration remains opt-in via requiring code_teams/rspec.

* refactor: make Testing.enable! client-controlled

Move RSpec configuration into enable! method so clients explicitly
opt-in rather than having it auto-run on require. This gives consumers
control over when testing infrastructure is activated.

* test: update specs to call enable! explicitly

Specs now call CodeTeams::Testing.enable! at the top level before
RSpec.describe, matching the intended client usage pattern.

* docs: add Testing section to README

Document how to use code_teams/rspec and Testing.enable! for
creating temporary teams in specs.

* chore: update unicode-emoji gem version

* refactor: have testing.rb require rspec.rb

This eliminates the conditional check for RSpecHelpers and simplifies
client usage - they only need to require code_teams/testing.

* refactor: rename rspec.rb to rspec_helpers.rb

File name now matches the module it defines.

* refactor: move deep_stringify_keys to Utils

Consolidates utility methods in one place.

* refactor: improve type signatures

- Add typed: strict sigil and signatures to Utils
- Use T::Hash[Symbol, T.untyped] for create_code_team attributes
- Fix nilable string handling in Plugin.default_data_accessor_name

* chore: remove accidentally committed local files

These belong in .git/info/exclude, not in the repo.

* test: remove redundant before/after blocks

The enable! around hook handles cleanup automatically.

* docs: simplify testing example to use built-in properties only

* refactor: improve more type signatures

- inherited(base) now typed as T.class_of(Plugin) instead of T.untyped
- raw_hash now typed as T::Hash[String, T.untyped] since YAML produces string keys

* chore: bump version to 1.2.0

* Install 1.2.0

* refactor: nest RSpecHelpers under Testing namespace

Move RSpecHelpers to CodeTeams::Testing::RSpecHelpers as suggested
in PR review. This better reflects the module hierarchy since
RSpecHelpers is part of the testing utilities.

Author: joemsak

Gemfile.lock

@@ -99,7 +99,7 @@ GEM
     thor (1.3.2)
     unicode-display_width (3.1.4)
       unicode-emoji (~> 4.0, >= 4.0.4)
-    unicode-emoji (4.0.4)
+    unicode-emoji (4.2.0)
     yard (0.9.37)
     yard-sorbet (0.9.0)
       sorbet-runtime

README.md

@@ -111,6 +111,32 @@ if errors.any?
 end
 ```
 
+## Testing
+
+`code_teams` provides test helpers for creating temporary teams in your specs without writing YML files to disk. Add the following to your `spec_helper.rb` (or `rails_helper.rb`):
+
+```ruby
+require 'code_teams/testing'
+
+CodeTeams::Testing.enable!
+```
+
+This gives you:
+- A `code_team_with_config` helper method available in all specs
+- Automatic cleanup of testing teams between examples
+
+Example usage in a spec:
+
+```ruby
+RSpec.describe 'my feature' do
+  it 'works with a team' do
+    team = code_team_with_config(name: 'Test Team')
+
+    expect(CodeTeams.find('Test Team')).to eq(team)
+  end
+end
+```
+
 ## Contributing
 
 Bug reports and pull requests are welcome!

lib/code_teams.rb

@@ -84,7 +84,7 @@ def self.from_yml(config_yml)
       )
     end
 
-    sig { params(raw_hash: T::Hash[T.untyped, T.untyped]).returns(Team) }
+    sig { params(raw_hash: T::Hash[String, T.untyped]).returns(Team) }
     def self.from_hash(raw_hash)
       new(
         config_yml: nil,
@@ -103,7 +103,7 @@ def self.register_plugins
       end
     end
 
-    sig { returns(T::Hash[T.untyped, T.untyped]) }
+    sig { returns(T::Hash[String, T.untyped]) }
     attr_reader :raw_hash
 
     sig { returns(T.nilable(String)) }
@@ -112,7 +112,7 @@ def self.register_plugins
     sig do
       params(
         config_yml: T.nilable(String),
-        raw_hash: T::Hash[T.untyped, T.untyped]
+        raw_hash: T::Hash[String, T.untyped]
       ).void
     end
     def initialize(config_yml:, raw_hash:)

lib/code_teams/plugin.rb

@@ -25,12 +25,12 @@ def self.data_accessor_name(key = default_data_accessor_name)
     sig { returns(String) }
     def self.default_data_accessor_name
       # e.g., MyNamespace::MyPlugin -> my_plugin
-      Utils.underscore(Utils.demodulize(name))
+      Utils.underscore(Utils.demodulize(T.must(name)))
     end
 
-    sig { params(base: T.untyped).void }
+    sig { params(base: T.class_of(Plugin)).void }
     def self.inherited(base) # rubocop:disable Lint/MissingSuper
-      all_plugins << T.cast(base, T.class_of(Plugin))
+      all_plugins << base
     end
 
     sig { returns(T::Array[T.class_of(Plugin)]) }

lib/code_teams/testing.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+#
+# typed: strict
+
+require 'securerandom'
+require 'code_teams'
+require 'code_teams/testing/rspec_helpers'
+
+module CodeTeams
+  # Utilities for tests that need a controlled set of teams without writing YML
+  # files to disk.
+  #
+  # Opt-in by requiring `code_teams/testing`.
+  module Testing
+    extend T::Sig
+
+    THREAD_KEY = T.let(:__code_teams_collection, Symbol)
+    @enabled = T.let(false, T::Boolean)
+
+    sig { void }
+    def self.enable!
+      return if @enabled
+
+      CodeTeams.prepend(CodeTeamsExtension)
+      @enabled = true
+
+      return unless defined?(RSpec)
+
+      T.unsafe(RSpec).configure do |config|
+        config.include CodeTeams::Testing::RSpecHelpers
+
+        config.around do |example|
+          example.run
+          # Bust caches because plugins may hang onto stale data between examples.
+          if CodeTeams::Testing.code_teams.any?
+            CodeTeams.bust_caches!
+            CodeTeams::Testing.reset!
+          end
+        end
+      end
+    end
+
+    sig { params(attributes: T::Hash[Symbol, T.untyped]).returns(CodeTeams::Team) }
+    def self.create_code_team(attributes)
+      attributes = attributes.dup
+      attributes[:name] ||= "Fake Team #{SecureRandom.hex(4)}"
+
+      code_team = CodeTeams::Team.new(
+        config_yml: 'tmp/fake_config.yml',
+        raw_hash: Utils.deep_stringify_keys(attributes)
+      )
+
+      code_teams << code_team
+      code_team
+    end
+
+    sig { returns(T::Array[CodeTeams::Team]) }
+    def self.code_teams
+      existing = Thread.current[THREAD_KEY]
+      return existing if existing.is_a?(Array)
+
+      Thread.current[THREAD_KEY] = []
+      T.cast(Thread.current[THREAD_KEY], T::Array[CodeTeams::Team])
+    end
+
+    sig { void }
+    def self.reset!
+      Thread.current[THREAD_KEY] = []
+    end
+
+    module CodeTeamsExtension
+      extend T::Sig
+
+      sig { params(base: Module).void }
+      def self.prepended(base)
+        base.singleton_class.prepend(ClassMethods)
+      end
+
+      module ClassMethods
+        extend T::Sig
+
+        sig { returns(T::Array[CodeTeams::Team]) }
+        def all
+          CodeTeams::Testing.code_teams + super
+        end
+
+        sig { params(name: String).returns(T.nilable(CodeTeams::Team)) }
+        def find(name)
+          CodeTeams::Testing.code_teams.find { |t| t.name == name } || super
+        end
+      end
+    end
+  end
+end

lib/code_teams/testing/rspec_helpers.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+#
+# typed: false
+
+require 'securerandom'
+require 'code_teams/testing'
+
+module CodeTeams
+  module Testing
+    module RSpecHelpers
+      def code_team_with_config(team_config = {})
+        team_config = team_config.dup
+        team_config[:name] ||= "Fake Team #{SecureRandom.hex(4)}"
+        CodeTeams::Testing.create_code_team(team_config)
+      end
+    end
+  end
+end

lib/code_teams/utils.rb

@@ -1,7 +1,14 @@
+# frozen_string_literal: true
+#
+# typed: strict
+
 module CodeTeams
   module Utils
+    extend T::Sig
+
     module_function
 
+    sig { params(string: String).returns(String) }
     def underscore(string)
       string.gsub('::', '/')
         .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
@@ -10,8 +17,24 @@ def underscore(string)
         .downcase
     end
 
+    sig { params(string: String).returns(String) }
     def demodulize(string)
-      string.split('::').last
+      T.must(string.split('::').last)
+    end
+
+    # Recursively converts symbol keys to strings. Top-level input should be a Hash.
+    sig { params(value: T.untyped).returns(T.untyped) }
+    def deep_stringify_keys(value)
+      case value
+      when Hash
+        value.each_with_object({}) do |(k, v), acc|
+          acc[k.to_s] = deep_stringify_keys(v)
+        end
+      when Array
+        value.map { |v| deep_stringify_keys(v) }
+      else
+        value
+      end
     end
   end
 end

spec/lib/code_teams/testing/r_spec_helpers_integration_spec.rb

@@ -0,0 +1,16 @@
+require 'code_teams/testing'
+
+CodeTeams::Testing.enable!
+
+RSpec.describe CodeTeams::Testing::RSpecHelpers do
+  it 'exposes code_team_with_config and makes the team discoverable' do
+    code_team_with_config(name: 'RSpec Team')
+
+    expect(CodeTeams.find('RSpec Team')).not_to be_nil
+  end
+
+  it 'cleans up testing teams between examples' do
+    expect(CodeTeams::Testing.code_teams).to be_empty
+    expect(CodeTeams.find('RSpec Team')).to be_nil
+  end
+end

spec/lib/code_teams/testing_spec.rb

@@ -0,0 +1,15 @@
+require 'code_teams/testing'
+
+CodeTeams::Testing.enable!
+
+RSpec.describe CodeTeams::Testing do
+  describe '.create_code_team' do
+    it 'adds the team to CodeTeams.all and CodeTeams.find' do
+      team = described_class.create_code_team({ name: 'Temp Team', extra_data: { foo: { bar: 1 } } })
+
+      expect(CodeTeams.all).to include(team)
+      expect(CodeTeams.find('Temp Team')).to eq(team)
+      expect(team.raw_hash.dig('extra_data', 'foo', 'bar')).to eq(1)
+    end
+  end
+end