rspec-let-analyzer 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a5a75ffed6c9e25926117f6412a8a12bd0bdf73824ae4683a75520dfd8eab28d
+  data.tar.gz: 14ae2f4a6ca4296a51f61f7a4acc75575c02b47fff5d7b6bdb0fa16c6f31ba47
+SHA512:
+  metadata.gz: 3d4c1d18085b7e31231d5376a6accde175352b34dd84722f344d1972d16673dd72f6b369ed340daa4dcd42701a1d5da474634677875e8b6847135c702af374a5
+  data.tar.gz: a6f0c225e2d97a56c1f3bd5c1d0788db9a30f3f6a91f6a30cc85183bce52b20944cfa023d8f5a687d0e090d9b08cbb735c2374a1c53012aadc46a81e5c10cef6

data/README.md

@@ -0,0 +1,183 @@
+# RSpec Let Analyzer
+
+A Ruby gem that analyzes RSpec test files to identify opportunities for refactoring `let` and `let!` declarations to use [test-prof](https://github.com/test-prof/test-prof)'s `let_it_be` helper for improved test performance.
+
+## Background
+
+The `let_it_be` helper from the test-prof gem creates test data once per example group instead of once per example, which can significantly speed up test suites. This tool helps you identify which `let` declarations are good candidates for conversion to `let_it_be`.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'rspec-let-analyzer'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install rspec-let-analyzer
+```
+
+## Usage
+
+Run the analyzer on your RSpec test suite:
+
+```bash
+# Analyze specs in current directory
+rspec-let-analyzer
+
+# Analyze specs in a different directory
+rspec-let-analyzer /path/to/project
+rspec-let-analyzer --directory /path/to/project
+```
+
+This will scan all files matching `spec/**/*_spec.rb` in the specified directory (or current directory if not specified) and display a table showing:
+
+- **Total**: Combined score of all metrics (Root + it blocks + Nest columns + Redef + Before Creates)
+- **Root**: Number of `let`/`let!` declarations at the root level of each describe block
+- **it blocks**: Number of test examples in each file
+- **Nest 1, Nest 2, etc.**: Number of `let` declarations at different nesting depths
+- **Redef**: Number of `let` redefinitions (where a nested context redefines a `let` from a parent scope)
+- **Bef Cr**: Number of `create` calls in `before` blocks
+
+### Command Line Options
+
+```bash
+# Show top 20 files instead of default 10
+rspec-let-analyzer -n 20
+
+# Output in different formats
+rspec-let-analyzer --format ascii  # Default: ASCII table
+rspec-let-analyzer --format json   # JSON for further processing
+rspec-let-analyzer --format html   # HTML report with Bootstrap styling
+rspec-let-analyzer --format llm    # LLM-friendly JSON for AI-assisted refactoring
+
+# Disable progress indicator
+rspec-let-analyzer --no-progress
+
+# Track nesting depth up to 5 levels (default: 3)
+rspec-let-analyzer --nesting 5
+
+# Disable nesting tracking entirely
+rspec-let-analyzer --no-nesting
+
+# Sort by different fields
+rspec-let-analyzer --sort total   # Sort by total score (default)
+rspec-let-analyzer --sort root    # Sort by root lets
+rspec-let-analyzer --sort it      # Sort by number of it blocks
+rspec-let-analyzer --sort redef   # Sort by number of redefinitions
+rspec-let-analyzer --sort before  # Sort by before creates
+
+# Track FactoryBot usage statistics
+rspec-let-analyzer --factories
+
+# Analyze a different directory
+rspec-let-analyzer --directory /path/to/project
+rspec-let-analyzer /path/to/project  # Positional argument also works
+
+# Display runtime performance metrics
+rspec-let-analyzer --runtime-metrics
+
+# Use a different adapter (default: prism)
+rspec-let-analyzer --adapter parser  # Requires 'gem install parser'
+
+# Generate reports and save to file
+rspec-let-analyzer --format html --output report.html
+rspec-let-analyzer --format llm --output refactor-guide.json
+
+# Show help
+rspec-let-analyzer --help
+```
+
+### LLM-Assisted Refactoring
+
+The `--format llm` option generates AI-friendly output designed for use with Large Language Models (like Claude, ChatGPT, etc.) to assist with refactoring:
+
+```bash
+# Generate refactoring guide
+rspec-let-analyzer --format llm --output refactor-guide.json -n 10
+
+# Then provide this to your AI assistant with a prompt like:
+# "Review the top 5 files in this report and suggest let_it_be refactorings"
+```
+
+The LLM format includes:
+- Prioritized list of refactoring candidates with scores
+- Step-by-step refactoring workflow
+- Decision criteria (when to keep/ask/revert changes)
+- Guidelines for safe conversions and common fixes
+- Context about factory usage patterns
+
+### Understanding the Output
+
+**High Total score** indicates files with the most opportunities for optimization, combining all metrics for a comprehensive view of complexity.
+
+**High numbers in the Root column** indicate files with many `let` declarations at the top level. These are prime candidates for `let_it_be` if:
+- The data doesn't change between tests
+- The tests don't modify the created objects
+
+**High numbers in Redef column** indicate files where `let` declarations are frequently overridden in nested contexts. These may be more complex to refactor since the redefinitions might be intentional for test isolation.
+
+**High numbers in Bef Cr column** indicate files with many `create` calls in `before` blocks, which can be converted to `let_it_be` or `before(:all)` blocks.
+
+**Factory tracking** shows which FactoryBot factories are used most frequently across your test suite, helping identify optimization opportunities.
+
+## Example Output
+
+```
++------------------------------------------------------------+----------+----------+----------+----------+----------+----------+----------+----------+
+| File                                                       |    Total |     Root | it blocks|   Nest 1 |   Nest 2 |   Nest 3+|    Redef |   Bef Cr |
++------------------------------------------------------------+----------+----------+----------+----------+----------+----------+----------+----------+
+| spec/models/user_spec.rb                                   |       50 |       12 |       25 |        8 |        3 |        0 |        2 |        0 |
+| spec/controllers/posts_controller_spec.rb                  |       38 |       10 |       18 |        6 |        2 |        1 |        1 |        0 |
++------------------------------------------------------------+----------+----------+----------+----------+----------+----------+----------+----------+
+| TOTAL (all 50 files)                                       |      600 |      150 |      300 |          |          |          |       15 |        0 |
++------------------------------------------------------------+----------+----------+----------+----------+----------+----------+----------+----------+
+```
+
+## Development
+
+After checking out the repo, run:
+
+```bash
+bundle install
+```
+
+To run the test suite:
+
+```bash
+bundle exec rspec
+```
+
+To install this gem onto your local machine:
+
+```bash
+bundle exec rake install
+```
+
+## How It Works
+
+The gem uses Ruby's [Prism](https://github.com/ruby/prism) parser to analyze RSpec files and identify:
+
+1. `let` and `let!` declarations at various nesting levels
+2. Context nesting depth for each declaration
+3. Cases where `let` declarations are redefined in nested scopes
+4. FactoryBot usage patterns (when enabled)
+
+This information helps you prioritize which test files to refactor for better performance using `let_it_be`.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub.
+
+## License
+
+The gem is available as open source under the terms of the MIT License.

data/bin/rspec-let-analyzer

@@ -0,0 +1,117 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../lib/rspec_let_analyzer'
+require 'optparse'
+
+# Parse command line options
+options = { limit: 10, format: 'ascii', progress: true, nesting: 3, sort: 'total', factories: false, directory: nil,
+            runtime_metrics: false, adapter: 'prism', output: nil }
+OptionParser.new do |opts|
+  opts.banner = 'Usage: rspec-let-analyzer [options] [DIRECTORY]'
+
+  opts.on('-n', '--number N', Integer, 'Number of spec files to show (default: 10)') do |n|
+    options[:limit] = n
+  end
+
+  opts.on('-f', '--format FORMAT', %w[ascii json html llm], 'Output format: ascii, json, html, llm (default: ascii)') do |f|
+    options[:format] = f
+  end
+
+  opts.on('--[no-]progress', 'Show progress while parsing (default: true)') do |p|
+    options[:progress] = p
+  end
+
+  opts.on('--nesting DEPTH', Integer, 'Max nesting depth to track (default: 3)') do |d|
+    if d <= 0
+      puts 'Error: nesting depth must be greater than 0'
+      puts 'Use --no-nesting to disable nesting tracking'
+      exit 1
+    end
+    options[:nesting] = d
+  end
+
+  opts.on('--no-nesting', 'Disable nesting tracking') do
+    options[:nesting] = nil
+  end
+
+  opts.on('-s', '--sort FIELD', %w[root it redef before total], 'Sort by field: root, it, redef, before, total (default: total)') do |s|
+    options[:sort] = s
+  end
+
+  opts.on('--factories', 'Track FactoryBot usage statistics') do
+    options[:factories] = true
+  end
+
+  opts.on('-d', '--directory DIR', 'Directory to analyze (default: current directory)') do |d|
+    options[:directory] = d
+  end
+
+  opts.on('--runtime-metrics', 'Display runtime performance metrics') do
+    options[:runtime_metrics] = true
+  end
+
+  opts.on('-a', '--adapter ADAPTER', %w[prism parser], 'Adapter to use: prism, parser (default: prism)') do |a|
+    options[:adapter] = a
+  end
+
+  opts.on('-o', '--output FILE', 'Write output to FILE instead of stdout') do |o|
+    options[:output] = o
+  end
+
+  opts.on('-h', '--help', 'Show this help message') do
+    puts opts
+    exit
+  end
+end.parse!
+
+# Accept directory as positional argument if not specified with --directory
+options[:directory] = ARGV[0] if ARGV.length.positive? && options[:directory].nil?
+
+# Run analysis
+progress_reporter = RSpecLetAnalyzer::ProgressReporter.new(options[:progress])
+analyzer = RSpecLetAnalyzer::Analyzer.new(
+  progress_reporter: progress_reporter,
+  nesting_depth: options[:nesting],
+  track_factories: options[:factories],
+  parser_type: options[:adapter].to_sym
+)
+
+analyze_start = Time.now
+analyzer.analyze(options[:directory])
+analyze_time = Time.now - analyze_start
+
+# Format and output
+formatter = case options[:format]
+            when 'json'
+              RSpecLetAnalyzer::Formatters::JsonFormatter.new
+            when 'html'
+              RSpecLetAnalyzer::Formatters::HtmlFormatter.new
+            when 'llm'
+              RSpecLetAnalyzer::Formatters::LlmFormatter.new
+            else
+              RSpecLetAnalyzer::Formatters::AsciiFormatter.new
+            end
+
+format_start = Time.now
+output = formatter.format(analyzer: analyzer, limit: options[:limit], sort_by: options[:sort])
+format_time = Time.now - format_start
+
+# Add runtime metrics if requested
+if options[:runtime_metrics]
+  runtime_metrics = {
+    analyze_time: analyze_time,
+    format_time: format_time,
+    total_time: analyze_time + format_time
+  }
+
+  output = formatter.add_runtime_metrics(output, runtime_metrics)
+end
+
+# Write output to file or stdout
+if options[:output]
+  File.write(options[:output], output)
+  puts "Report written to #{options[:output]}"
+else
+  puts output
+end

data/lib/rspec_let_analyzer/adapter.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module RSpecLetAnalyzer
+  # Base class for parser adapters
+  # Each adapter must implement: parse_file, visit_tree
+  class Adapter
+    class << self
+      def create(type)
+        case type
+        when 'prism', :prism
+          require_relative 'adapters/prism_adapter'
+          Adapters::PrismAdapter.new
+        when 'parser', :parser
+          require_relative 'adapters/parser_adapter'
+          Adapters::ParserAdapter.new
+        else
+          # :nocov:
+          raise ArgumentError, "Unknown parser type: #{type}"
+          # :nocov:
+        end
+      end
+    end
+
+    # :nocov:
+    # Parse a file and return an AST
+    # @param file_path [String] path to the file to parse
+    # @return [Object] AST representation
+    def parse_file(_file_path)
+      raise NotImplementedError, "#{self.class} must implement #parse_file"
+    end
+
+    # Parse code string and return an AST
+    # @param code [String] Ruby code to parse
+    # @return [Object] AST representation
+    def parse(_code)
+      raise NotImplementedError, "#{self.class} must implement #parse"
+    end
+
+    # Visit the AST and collect statistics
+    # @param ast [Object] the AST to visit
+    # @param visitor [Visitor] the visitor to use
+    # @return [void]
+    def visit_tree(_ast, _visitor)
+      raise NotImplementedError, "#{self.class} must implement #visit_tree"
+    end
+    # :nocov:
+  end
+end

data/lib/rspec_let_analyzer/adapters/parser_adapter.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+begin
+  require 'parser/current'
+rescue LoadError
+  # :nocov:
+  raise LoadError, "The 'parser' gem is not installed. Install it with: gem install parser"
+  # :nocov:
+end
+
+module RSpecLetAnalyzer
+  module Adapters
+    class ParserAdapter < Adapter
+      def parse_file(file_path)
+        Parser::CurrentRuby.parse_file(file_path)
+      end
+
+      def parse(code)
+        Parser::CurrentRuby.parse(code)
+      end
+
+      def visit_tree(ast, visitor)
+        visitor.process(ast)
+      end
+    end
+  end
+end

data/lib/rspec_let_analyzer/adapters/prism_adapter.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'prism'
+
+module RSpecLetAnalyzer
+  module Adapters
+    class PrismAdapter < Adapter
+      def parse_file(file_path)
+        Prism.parse_file(file_path)
+      end
+
+      def parse(code)
+        Prism.parse(code)
+      end
+
+      def visit_tree(ast, visitor)
+        ast.value.accept(visitor)
+      end
+    end
+  end
+end

data/lib/rspec_let_analyzer/analyzer.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module RSpecLetAnalyzer
+  class Analyzer
+    attr_reader :results, :totals, :nesting_depth, :factory_stats
+
+    def initialize(progress_reporter:, nesting_depth:, track_factories:, parser_type: :prism)
+      @results = []
+      @nesting_depth = nesting_depth
+      @track_factories = track_factories
+      @totals = build_totals_hash
+      @factory_stats = Hash.new(0) if track_factories
+      @progress_reporter = progress_reporter
+      @adapter = Adapter.create(parser_type)
+      @parser_type = parser_type
+    end
+
+    def analyze(path = nil)
+      # Build pattern based on path
+      # If path looks like a glob pattern (contains * or ends with .rb), use it directly
+      # Otherwise treat it as a directory and append spec/**/*_spec.rb
+      pattern = if path.nil?
+                  'spec/**/*_spec.rb'
+                elsif path.include?('*') || path.end_with?('.rb')
+                  # It's a glob pattern or specific file, use as-is
+                  path
+                else
+                  # It's a directory, append spec pattern
+                  File.join(path, 'spec/**/*_spec.rb')
+                end
+
+      spec_files = Dir.glob(pattern)
+      total_files = spec_files.size
+
+      @results = spec_files.each_with_index.map do |file, index|
+        @progress_reporter&.update(current: index + 1, total: total_files, file: file)
+
+        ast = @adapter.parse_file(file)
+        visitor = create_visitor
+        @adapter.visit_tree(ast, visitor)
+
+        # Aggregate factory usage
+        if @track_factories && visitor.factory_usage
+          visitor.factory_usage.each do |factory, count|
+            @factory_stats[factory] += count
+          end
+        end
+
+        file_result = {
+          file: file,
+          root_lets: visitor.root_lets,
+          it_blocks: visitor.total_its,
+          redefinitions: visitor.redefinitions,
+          before_creates: visitor.before_creates
+        }
+
+        if @nesting_depth
+          visitor.nesting_counts.each_with_index do |count, i|
+            file_result[:"nesting_#{i + 1}"] = count
+          end
+        end
+
+        # Calculate total score
+        file_result[:total_score] = calculate_file_total_score(file_result, visitor)
+
+        file_result
+      end
+
+      @progress_reporter&.clear
+      calculate_totals
+    end
+
+    def top(limit, sort_by)
+      sort_key = case sort_by
+                 when 'root'
+                   :root_lets
+                 when 'it'
+                   :it_blocks
+                 when 'redef'
+                   :redefinitions
+                 when 'before'
+                   :before_creates
+                 when 'total'
+                   :total_score
+                 end
+
+      @results.sort_by { |r| -r[sort_key] }.take(limit)
+    end
+
+    def top_factories(limit)
+      return nil unless @track_factories
+
+      @factory_stats.sort_by { |_factory, count| -count }.take(limit)
+    end
+
+    private
+
+    def create_visitor
+      case @parser_type
+      when :prism, 'prism'
+        Visitors::PrismVisitor.new(@nesting_depth, @track_factories)
+      when :parser, 'parser'
+        Visitors::ParserVisitor.new(@nesting_depth, @track_factories)
+      else
+        raise ArgumentError, "Unknown parser type: #{@parser_type}"
+      end
+    end
+
+    def build_totals_hash
+      totals = { root_lets: 0, it_blocks: 0, redefinitions: 0, before_creates: 0, total_score: 0 }
+      @nesting_depth&.times do |i|
+        totals[:"nesting_#{i + 1}"] = 0
+      end
+      totals
+    end
+
+    def calculate_totals
+      @totals = @results.each_with_object(build_totals_hash) do |r, acc|
+        acc[:root_lets] += r[:root_lets]
+        acc[:it_blocks] += r[:it_blocks]
+        acc[:redefinitions] += r[:redefinitions]
+        acc[:before_creates] += r[:before_creates]
+        acc[:total_score] += r[:total_score]
+
+        @nesting_depth&.times do |i|
+          acc[:"nesting_#{i + 1}"] += r[:"nesting_#{i + 1}"]
+        end
+      end
+    end
+
+    def calculate_file_total_score(file_result, visitor)
+      total = file_result[:root_lets] + file_result[:it_blocks] +
+              file_result[:redefinitions] + file_result[:before_creates]
+
+      if @nesting_depth
+        visitor.nesting_counts.each do |count|
+          total += count
+        end
+      end
+
+      total
+    end
+  end
+end

data/lib/rspec_let_analyzer/formatters/ascii_formatter.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module RSpecLetAnalyzer
+  module Formatters
+    class AsciiFormatter
+      def format(analyzer:, limit:, sort_by:)
+        sorted = analyzer.top(limit, sort_by)
+        totals = analyzer.totals
+        total_files = analyzer.results.size
+        nesting_depth = analyzer.nesting_depth
+
+        # Calculate column widths
+        base_width = 60
+        col_width = 10
+
+        # Build header
+        output = []
+
+        # Calculate total table width
+        num_cols = 5 + (nesting_depth || 0) # Root, it blocks, Redef, Before Creates, Total + nesting columns
+        separator = "+#{(['-' * base_width] + (['-' * col_width] * num_cols)).join('+')}+"
+
+        output << separator
+
+        # Header row
+        headers = ['File', 'Total', 'Root', 'it blocks']
+        if nesting_depth
+          (1...nesting_depth).each { |i| headers << "Nest #{i}" }
+          headers << "Nest #{nesting_depth}+"
+        end
+        headers << 'Redef'
+        headers << 'Bef Cr'
+
+        header_format = "| %-58s |#{' %8s |' * (headers.size - 1)}"
+        output << (header_format % headers)
+        output << separator
+
+        # Data rows
+        sorted.each do |result|
+          file_display = result[:file].size > 58 ? "...#{result[:file][-55..]}" : result[:file]
+          values = [file_display, result[:total_score], result[:root_lets], result[:it_blocks]]
+
+          nesting_depth&.times do |i|
+            values << result[:"nesting_#{i + 1}"]
+          end
+
+          values << result[:redefinitions]
+          values << result[:before_creates]
+
+          row_format = "| %-58s |#{' %8d |' * (values.size - 1)}"
+          output << (row_format % values)
+        end
+
+        # Totals row
+        output << separator
+        total_values = ["TOTAL (all #{total_files} files)", totals[:total_score], totals[:root_lets], totals[:it_blocks]]
+
+        nesting_depth&.times { total_values << '' }
+
+        total_values << totals[:redefinitions]
+        total_values << totals[:before_creates]
+
+        total_format = '| %-58s | %8d | %8d | %8d |'
+        total_format += (' %8s |' * nesting_depth) if nesting_depth
+        total_format += ' %8d | %8d |'
+
+        output << (total_format % total_values)
+        output << separator
+
+        formatted_output = output.join("\n")
+
+        # Add FactoryBot section if enabled
+        formatted_output += "\n\n#{format_factory_stats(analyzer, limit)}" if analyzer.factory_stats
+
+        formatted_output
+      end
+
+      private
+
+      def format_factory_stats(analyzer, limit)
+        top_factories = analyzer.top_factories(limit)
+        return '' if top_factories.nil? || top_factories.empty?
+
+        output = []
+        output << "FactoryBot Usage (Top #{limit})"
+        output << "+#{'-' * 40}+#{'-' * 15}+"
+        output << '| Factory                                |   Usage Count |'
+        output << "+#{'-' * 40}+#{'-' * 15}+"
+
+        top_factories.each do |factory, count|
+          factory_display = factory.to_s.size > 38 ? "#{factory.to_s[0..34]}..." : factory.to_s
+          output << Kernel.format('| %-38s | %13d |', factory_display, count)
+        end
+
+        output << "+#{'-' * 40}+#{'-' * 15}+"
+
+        total_usage = analyzer.factory_stats.values.sum
+        total_unique = analyzer.factory_stats.size
+        output << ''
+        output << "Total unique factories: #{total_unique}"
+        output << "Total factory usage: #{total_usage}"
+
+        output.join("\n")
+      end
+
+      public
+
+      def add_runtime_metrics(output, metrics)
+        output += "\n\n"
+        output += "Runtime Metrics:\n"
+        output += "  Analysis: #{format_duration(metrics[:analyze_time])}\n"
+        output += "  Formatting: #{format_duration(metrics[:format_time])}\n"
+        output += "  Total: #{format_duration(metrics[:total_time])}"
+        output
+      end
+
+      private
+
+      def format_duration(seconds)
+        if seconds < 1
+          "#{(seconds * 1000).round(2)}ms"
+        else
+          "#{seconds.round(2)}s"
+        end
+      end
+    end
+  end
+end