fixture_kit 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 41dfc0a3fb06edb02068d8127c89708ec7e2c5792b40fb031ee553716a7c54ca
-  data.tar.gz: 4193bec6652924d99a7f564212087afa7f678b1f7995fca67f883dcfb1a45d24
+  metadata.gz: 6ccc3496f3e23da0877bac37e98d2fd325daf737f4d7bc2988d80156d202c248
+  data.tar.gz: 332a5f7824ec4c449ef052bf67616c71b7bca07749f69dcb9c1369afbb95f1a4
 SHA512:
-  metadata.gz: e9d7108cd6bda22319c02ea76384772210bdbea00f3ac93c6f6263dd72f5d7475f4cb0087f57f2d316dd17bc2fe36ad3597e87a417dae8149b0404f9196e6a0f
-  data.tar.gz: 25c72f2db8d0c93e06e244acc12d224ec36a0cbb85cbbd65c9a4a9d92268b76847c9fb0150508f78d2a1446a7c66587b3c5d479b701c2f072d97e6df92ec289d
+  metadata.gz: aaab87039e3f040b6b1f200a2e853e46263449f2bc900f664d167b009adffb2eccd48fc9080051b67dc6ad8c1e12f3aca4796db45ced24f63ad35f671cddb7f6
+  data.tar.gz: 55d185c158111d9a892ceb558af729f48a2708c4975e1365a411bdbbb6a6e26d776fd511bc9505dc818aa4e4747062acb5b51b514c3efe43351ff342e036a3e9

data/README.md

@@ -89,6 +89,26 @@ end
 - ActiveRecord >= 8.0
 - ActiveSupport >= 8.0
 
+## Releasing
+
+1. Bump the version in `lib/fixture_kit/version.rb`
+2. Update lockfiles:
+   ```sh
+   bundle install
+   cd spec/dummy && bundle install && cd ../..
+   bundle exec appraisal install
+   ```
+3. Commit and push to main:
+   ```sh
+   git add lib/fixture_kit/version.rb spec/dummy/Gemfile.lock gemfiles/*.gemfile.lock
+   git commit -m "Release vX.Y.Z"
+   git push
+   ```
+4. Create a GitHub release:
+   ```sh
+   gh release create vX.Y.Z --title "vX.Y.Z" --target main --generate-notes
+   ```
+
 ## License
 
 MIT. See [LICENSE](LICENSE).

data/lib/fixture_kit/analyzer/ast_factory_detector.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "prism"
+require "set"
+
+module FixtureKit
+  module Analyzer
+    class AstFactoryDetector
+      FACTORY_METHODS = %w[create build build_stubbed create_list build_list].to_set.freeze
+
+      def initialize
+        @file_cache = {}
+      end
+
+      # Returns array of factory name strings, e.g. ["company", "employee"]
+      def detect(mod, method_name)
+        meth = mod.instance_method(method_name)
+        file, line = meth.source_location
+        return [] unless file && File.exist?(file)
+
+        ast = parse_file(file)
+        block = find_block_at_line(ast, line)
+        return [] unless block
+
+        collect_factory_calls(block)
+      rescue
+        []
+      end
+
+      private
+
+      def parse_file(path)
+        @file_cache[path] ||= Prism.parse(File.read(path)).value
+      end
+
+      # Find the block node that starts at the target line.
+      def find_block_at_line(node, target_line)
+        if node.is_a?(Prism::BlockNode) && node.location.start_line == target_line
+          return node
+        end
+
+        node.child_nodes.compact.each do |child|
+          found = find_block_at_line(child, target_line)
+          return found if found
+        end
+
+        nil
+      end
+
+      # Walk an AST subtree collecting factory call argument symbols.
+      def collect_factory_calls(node)
+        results = []
+
+        if node.is_a?(Prism::CallNode) && FACTORY_METHODS.include?(node.name.to_s)
+          first_arg = node.arguments&.arguments&.first
+          results << first_arg.value if first_arg.is_a?(Prism::SymbolNode)
+        end
+
+        node.child_nodes.compact.each { |child| results.concat(collect_factory_calls(child)) }
+        results
+      end
+    end
+  end
+end

data/lib/fixture_kit/analyzer/file_result.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module FixtureKit
+  module Analyzer
+    class FileResult
+      attr_reader :file, :total_examples, :lets
+
+      def initialize(file:, total_examples:, lets:)
+        @file = file
+        @total_examples = total_examples
+        @lets = lets.sort_by { |l| -l.example_count }
+      end
+
+      def max_reuse
+        lets.first&.example_count || 0
+      end
+
+      def to_h
+        {
+          file: file,
+          total_examples: total_examples,
+          max_reuse: max_reuse,
+          lets: lets.map(&:to_h),
+        }
+      end
+    end
+  end
+end

data/lib/fixture_kit/analyzer/group_analyzer.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module FixtureKit
+  module Analyzer
+    class GroupAnalyzer
+      def initialize(detector: AstFactoryDetector.new)
+        @detector = detector
+      end
+
+      # Check if a group directly defines a let with this name
+      def group_defines_let?(group, let_name)
+        own_mod = group.const_get(:LetDefinitions, false)
+        own_mod.instance_methods(false).include?(let_name.to_sym)
+      rescue NameError
+        false
+      end
+
+      # Count examples that inherit a let defined at `group`, stopping at overrides
+      def examples_using_let(group, let_name)
+        count = group.examples.count
+        group.children.each do |child|
+          next if group_defines_let?(child, let_name)
+          count += examples_using_let(child, let_name)
+        end
+        count
+      end
+
+      # Total examples in group + all descendants
+      def total_examples(group)
+        group.examples.count + group.children.sum { |c| total_examples(c) }
+      end
+
+      # Walk tree, collect factory lets
+      def analyze(group, results = [])
+        own_mod = begin
+          group.const_get(:LetDefinitions, false)
+        rescue NameError
+          nil
+        end
+
+        if own_mod
+          own_mod.instance_methods(false).each do |method_name|
+            factories = @detector.detect(own_mod, method_name)
+            next if factories.empty?
+
+            loc = own_mod.instance_method(method_name).source_location
+            example_count = examples_using_let(group, method_name.to_s)
+
+            results << LetDefinition.new(
+              name: method_name.to_s,
+              factories: factories,
+              example_count: example_count,
+              file: loc&.first,
+              line: loc&.last,
+              group_description: group.description.to_s[0, 80],
+            )
+          end
+        end
+
+        group.children.each { |child| analyze(child, results) }
+        results
+      end
+    end
+  end
+end

data/lib/fixture_kit/analyzer/let_definition.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module FixtureKit
+  module Analyzer
+    class LetDefinition
+      attr_reader :name, :factories, :example_count, :file, :line, :group_description
+
+      def initialize(name:, factories:, example_count:, file:, line:, group_description:)
+        @name = name
+        @factories = factories
+        @example_count = example_count
+        @file = file
+        @line = line
+        @group_description = group_description
+      end
+
+      def defined_at
+        "#{file}:#{line}"
+      end
+
+      def to_h
+        {
+          let_name: name,
+          factories: factories,
+          example_count: example_count,
+          defined_at: defined_at,
+          group: group_description,
+        }
+      end
+    end
+  end
+end

data/lib/fixture_kit/analyzer/runner.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "json"
+
+module FixtureKit
+  module Analyzer
+    class Runner
+      def initialize(
+        format: ENV.fetch("ANALYZER_FORMAT", "text"),
+        limit: ENV.fetch("ANALYZER_LIMIT", "50").to_i,
+        lets_per_file: ENV.fetch("ANALYZER_LETS_PER_FILE", "8").to_i,
+        min_reuse: ENV.fetch("ANALYZER_MIN_REUSE", "2").to_i,
+        output_path: ENV["ANALYZER_OUTPUT"]
+      )
+        @format = format
+        @limit = limit
+        @lets_per_file = lets_per_file
+        @min_reuse = min_reuse
+        @output_path = output_path
+      end
+
+      def run(example_groups)
+        return if example_groups.empty?
+
+        total = example_groups.length
+        $stderr.puts "[fixture_kit:analyzer] Analyzing #{total} top-level example groups..."
+
+        analyzer = GroupAnalyzer.new
+
+        by_file = Hash.new { |h, k| h[k] = {lets: [], total_examples: 0} }
+
+        example_groups.each_with_index do |group, idx|
+          file = group.metadata[:file_path] || group.metadata[:absolute_file_path] || "unknown"
+          if (idx + 1) % 500 == 0 || idx + 1 == total
+            $stderr.puts "[fixture_kit:analyzer] Processing group #{idx + 1}/#{total} (#{file})"
+          end
+          by_file[file][:total_examples] += analyzer.total_examples(group)
+          analyzer.analyze(group, by_file[file][:lets])
+        end
+
+        results = by_file.map do |file, data|
+          FileResult.new(file: file, total_examples: data[:total_examples], lets: data[:lets])
+        end.sort_by { |r| -r.max_reuse }
+
+        output(results)
+        results
+      end
+
+      # Install the at_exit hook that runs the analyzer after rspec --dry-run
+      def self.install_rspec_hook!
+        load_start = Time.now
+
+        progress_thread = Thread.new do
+          last_count = 0
+          loop do
+            sleep 5
+            current = ::RSpec.world.example_groups.length rescue 0
+            if current != last_count
+              $stderr.puts "[fixture_kit:analyzer] Loading... #{current} top-level groups found (#{(Time.now - load_start).round(1)}s)"
+              last_count = current
+            end
+          end
+        end
+        progress_thread.abort_on_exception = false
+
+        at_exit do
+          progress_thread.kill
+          next unless defined?(::RSpec) && ::RSpec.world.example_groups.any?
+
+          $stderr.puts "[fixture_kit:analyzer] Spec loading complete: #{::RSpec.world.example_groups.length} groups in #{(Time.now - load_start).round(1)}s"
+          new.run(::RSpec.world.example_groups)
+        end
+      end
+
+      private
+
+      def output(results)
+        case @format
+        when "json"
+          json = JSON.pretty_generate(results.map(&:to_h))
+          $stdout.puts json
+        else
+          TextFormatter.new(
+            limit: @limit,
+            lets_per_file: @lets_per_file,
+            min_reuse: @min_reuse,
+          ).render(results)
+        end
+
+        if @output_path
+          File.write(@output_path, JSON.pretty_generate(results.map(&:to_h)))
+          $stderr.puts "[fixture_kit:analyzer] Full JSON written to: #{@output_path}"
+        end
+      end
+    end
+  end
+end

data/lib/fixture_kit/analyzer/text_formatter.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module FixtureKit
+  module Analyzer
+    class TextFormatter
+      def initialize(limit:, lets_per_file:, min_reuse:, io: $stdout)
+        @limit = limit
+        @lets_per_file = lets_per_file
+        @min_reuse = min_reuse
+        @io = io
+      end
+
+      def render(results)
+        filtered = results.select { |r| r.max_reuse >= @min_reuse }
+
+        @io.puts
+        @io.puts "=" * 110
+        @io.puts "FACTORY LET REUSE (ranked by highest single-let example count)"
+        @io.puts "=" * 110
+        @io.puts
+        @io.puts "#{results.length} spec files analyzed, #{filtered.length} with max reuse >= #{@min_reuse}"
+
+        filtered.first(@limit).each_with_index do |result, idx|
+          @io.puts
+          @io.puts "#{idx + 1}. #{result.file}"
+          @io.puts "   examples: #{result.total_examples}  |  factory lets: #{result.lets.length}  |  max reuse: #{result.max_reuse}"
+          @io.puts "   " + "-" * 95
+
+          result.lets.first(@lets_per_file).each do |l|
+            @io.puts Kernel.format("   let(:%s)  examples: %d  factories: %s",
+              l.name, l.example_count, l.factories.join(", "))
+            @io.puts "      group: #{l.group_description}"
+          end
+
+          remaining = result.lets.length - @lets_per_file
+          @io.puts "   ... +#{remaining} more" if remaining > 0
+        end
+
+        @io.puts
+      end
+    end
+  end
+end

data/lib/fixture_kit/analyzer.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+# FixtureKit::Analyzer — Find high-ROI FixtureKit optimization targets.
+#
+# Analyzes RSpec specs via --dry-run to find factory_bot `let` blocks
+# and rank them by how many examples each `let` is shared across.
+# The more examples share a let, the bigger the speedup from caching
+# it with FixtureKit.
+#
+# Usage:
+#   rspec --dry-run --require fixture_kit/analyzer [spec files or dirs...]
+#
+# Options (via env vars):
+#   ANALYZER_FORMAT=text|json    Output format (default: text)
+#   ANALYZER_LIMIT=N             Max files to show (default: 50)
+#   ANALYZER_LETS_PER_FILE=N     Max lets to show per file (default: 8)
+#   ANALYZER_MIN_REUSE=N         Only show files with max reuse >= N (default: 2)
+#   ANALYZER_OUTPUT=path         Write JSON to file (default: none)
+
+module FixtureKit
+  module Analyzer
+    autoload :AstFactoryDetector, File.expand_path("analyzer/ast_factory_detector", __dir__)
+    autoload :GroupAnalyzer,      File.expand_path("analyzer/group_analyzer", __dir__)
+    autoload :LetDefinition,      File.expand_path("analyzer/let_definition", __dir__)
+    autoload :FileResult,         File.expand_path("analyzer/file_result", __dir__)
+    autoload :TextFormatter,      File.expand_path("analyzer/text_formatter", __dir__)
+    autoload :Runner,             File.expand_path("analyzer/runner", __dir__)
+  end
+end
+
+# Auto-hook into RSpec when loaded via --require
+if defined?(RSpec)
+  FixtureKit::Analyzer::Runner.install_rspec_hook!
+end

data/lib/fixture_kit/cache.rb

@@ -1,14 +1,10 @@
 # frozen_string_literal: true
 
-require "json"
-require "fileutils"
 require "active_support/core_ext/array/wrap"
-require "active_support/inflector"
 
 module FixtureKit
   class Cache
     ANONYMOUS_DIRECTORY = "_anonymous"
-    MemoryData = Data.define(:records, :exposed)
 
     include ConfigurationHelper
 
@@ -19,7 +15,7 @@ module FixtureKit
     end
 
     def path
-      File.join(configuration.cache_path, "#{identifier}.json")
+      file_cache.path
     end
 
     def identifier
@@ -34,7 +30,11 @@ module FixtureKit
     end
 
     def exists?
-      data || File.exist?(path)
+      data || file_cache.exists?
+    end
+
+    def clear_memory
+      @data = nil
     end
 
     def load
@@ -42,7 +42,7 @@ module FixtureKit
         raise FixtureKit::CacheMissingError, "Cache does not exist for fixture '#{fixture.identifier}'"
       end
 
-      @data ||= load_memory_data
+      @data ||= file_cache.read
       statements_by_connection(data.records).each do |connection, statements|
         connection.disable_referential_integrity do
           # execute_batch is private in current supported Rails versions.
@@ -64,17 +64,23 @@ module FixtureKit
           captured_models.concat(fixture.parent.cache.data.records.keys)
         end
 
-        @data = MemoryData.new(
+        @data = MemoryCache.new(
           records: generate_statements(captured_models),
-          exposed: build_exposed_mapping(fixture.definition.exposed)
+          exposed: file_cache.serialize_exposed(fixture.definition.exposed)
         )
       end
 
-      save_file_data
+      file_cache.write(data)
     end
 
     private
 
+    def file_cache
+      @file_cache ||= FileCache.new(
+        File.join(configuration.cache_path, "#{identifier}.json")
+      )
+    end
+
     def generate_statements(models)
       models.uniq.each_with_object({}) do |model, statements|
         columns = model.column_names
@@ -104,16 +110,6 @@ module FixtureKit
       "INSERT INTO #{quoted_table} (#{quoted_columns.join(", ")}) VALUES #{rows.join(", ")}"
     end
 
-    def build_exposed_mapping(exposed)
-      exposed.each_with_object({}) do |(name, record), hash|
-        if record.is_a?(Array)
-          hash[name] = record.map { |record| { record.class => record.id } }
-        else
-          hash[name] = { record.class => record.id }
-        end
-      end
-    end
-
     def statements_by_connection(records)
       deleted_tables = Set.new
 
@@ -129,27 +125,5 @@ module FixtureKit
         grouped[connection] << sql if sql
       end
     end
-
-    def load_memory_data
-      file_data = JSON.parse(File.read(path))
-      records = file_data.fetch("records").transform_keys do |model_name|
-        ActiveSupport::Inflector.constantize(model_name)
-      end
-
-      exposed = file_data.fetch("exposed").each_with_object({}) do |(name, value), hash|
-        if value.is_a?(Array)
-          hash[name.to_sym] = value.map { |r| { ActiveSupport::Inflector.constantize(r.keys.first) => r.values.first } }
-        else
-          hash[name.to_sym] = { ActiveSupport::Inflector.constantize(value.keys.first) => value.values.first }
-        end
-      end
-
-      MemoryData.new(records: records, exposed: exposed)
-    end
-
-    def save_file_data
-      FileUtils.mkdir_p(File.dirname(path))
-      File.write(path, JSON.pretty_generate(data.to_h))
-    end
   end
 end

data/lib/fixture_kit/file_cache.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+require "active_support/inflector"
+
+module FixtureKit
+  class FileCache
+    attr_reader :path
+
+    def initialize(path)
+      @path = path
+    end
+
+    def exists?
+      File.exist?(path)
+    end
+
+    def read
+      file_data = JSON.parse(File.read(path))
+      records = file_data.fetch("records").transform_keys do |model_name|
+        ActiveSupport::Inflector.constantize(model_name)
+      end
+
+      exposed = file_data.fetch("exposed").each_with_object({}) do |(name, value), hash|
+        if value.is_a?(Array)
+          hash[name.to_sym] = value.map { |r| { ActiveSupport::Inflector.constantize(r.keys.first) => r.values.first } }
+        else
+          hash[name.to_sym] = { ActiveSupport::Inflector.constantize(value.keys.first) => value.values.first }
+        end
+      end
+
+      MemoryCache.new(records: records, exposed: exposed)
+    end
+
+    def write(data)
+      FileUtils.mkdir_p(File.dirname(path))
+      File.write(path, JSON.pretty_generate(data.to_h))
+    end
+
+    def serialize_exposed(exposed)
+      exposed.each_with_object({}) do |(name, record), hash|
+        if record.is_a?(Array)
+          hash[name] = record.map { |record| { record.class => record.id } }
+        else
+          hash[name] = { record.class => record.id }
+        end
+      end
+    end
+  end
+end

data/lib/fixture_kit/fixture.rb

@@ -36,8 +36,16 @@ module FixtureKit
       emit(:cache_mounted) { @cache.load }
     end
 
+    def finish
+      @cache.clear_memory if anonymous?
+    end
+
     private
 
+    def anonymous?
+      !identifier.is_a?(String)
+    end
+
     def emit(event)
       cache_identifier = @cache.identifier
       unless block_given?

data/lib/fixture_kit/memory_cache.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module FixtureKit
+  class MemoryCache
+    attr_reader :records, :exposed
+
+    def initialize(records:, exposed:)
+      @records = records
+      @exposed = exposed
+      freeze
+    end
+
+    def to_h
+      { records: records, exposed: exposed }
+    end
+  end
+end

data/lib/fixture_kit/minitest.rb

@@ -23,6 +23,8 @@ module FixtureKit
         end
 
         super
+
+        declaration&.finish
       end
     end
 

data/lib/fixture_kit/rspec.rb

@@ -35,6 +35,10 @@ module FixtureKit
         prepend_before(:context) do
           self.class.metadata[DECLARATION_METADATA_KEY].generate
         end
+
+        append_after(:context) do
+          self.class.metadata[DECLARATION_METADATA_KEY].finish
+        end
       end
     end
 

data/lib/fixture_kit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module FixtureKit
-  VERSION = "0.10.0"
+  VERSION = "0.11.0"
 end

data/lib/fixture_kit.rb

@@ -21,6 +21,8 @@ module FixtureKit
   autoload :Repository, File.expand_path("fixture_kit/repository", __dir__)
   autoload :SqlSubscriber, File.expand_path("fixture_kit/sql_subscriber", __dir__)
   autoload :Cache, File.expand_path("fixture_kit/cache", __dir__)
+  autoload :FileCache, File.expand_path("fixture_kit/file_cache", __dir__)
+  autoload :MemoryCache, File.expand_path("fixture_kit/memory_cache", __dir__)
   autoload :Runner, File.expand_path("fixture_kit/runner", __dir__)
   autoload :Adapter, File.expand_path("fixture_kit/adapter", __dir__)
   autoload :MinitestAdapter, File.expand_path("fixture_kit/adapters/minitest_adapter", __dir__)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fixture_kit
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.11.0
 platform: ruby
 authors:
 - Ngan Pham
@@ -151,12 +151,21 @@ files:
 - lib/fixture_kit/adapter.rb
 - lib/fixture_kit/adapters/minitest_adapter.rb
 - lib/fixture_kit/adapters/rspec_adapter.rb
+- lib/fixture_kit/analyzer.rb
+- lib/fixture_kit/analyzer/ast_factory_detector.rb
+- lib/fixture_kit/analyzer/file_result.rb
+- lib/fixture_kit/analyzer/group_analyzer.rb
+- lib/fixture_kit/analyzer/let_definition.rb
+- lib/fixture_kit/analyzer/runner.rb
+- lib/fixture_kit/analyzer/text_formatter.rb
 - lib/fixture_kit/cache.rb
 - lib/fixture_kit/callbacks.rb
 - lib/fixture_kit/configuration.rb
 - lib/fixture_kit/configuration_helper.rb
 - lib/fixture_kit/definition.rb
+- lib/fixture_kit/file_cache.rb
 - lib/fixture_kit/fixture.rb
+- lib/fixture_kit/memory_cache.rb
 - lib/fixture_kit/minitest.rb
 - lib/fixture_kit/registry.rb
 - lib/fixture_kit/repository.rb