ruby_method_tracer 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e5fe5404bd1497820b14ca1e4bc041f778cfe9bc02402a4456329c88d0096206
-  data.tar.gz: cb08942010ab25a16a604d0edb973bd9f889e3c34ba2ae24ead8a0dcceed4ca8
+  metadata.gz: 35c8ff07ff1fff38a22779065d538545ec642a043b723da76b784ee97d9a24c8
+  data.tar.gz: a391814be17a97f5b6820355ba21f71eb8b3ffe381589f11ddccc41f6be7c691
 SHA512:
-  metadata.gz: f68e49cde1042577a5ed2f0054c263391070f29574d81bc58f6ec5db6f688f31411572372cce95eef010fbd6fc7cd981f38905cc01615eea914a680393af850a
-  data.tar.gz: 54b2ccc817924cd256dfdcfb66011acfa8641b76f66d2cb0ef59dab48e32f4d2bfa9d56d56d403f5bf60b53c627d784731984e0f61fc8ad01714576eba531620
+  metadata.gz: a2b2c43903841a2603c5dbd2032faa11facf0c3654bb8af6b32ab88a85777e095976f4ffbfd9448efd8a9644f5be5fde4e37524ac1e4cf733fbe078b1b93ea73
+  data.tar.gz: c0f7126d5a885e1f4943e00651fc51ff97b614f17b86035e6fa81c083a6a74705376762f7d87a006f4e5691cdd68bc900210836a675e5ecd58d4f6e6d47f3b24

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 ## [Unreleased]
 
+## [0.3.1] - 2025-11-22
+
+### Fixed
+- Fixed file permissions for `call_tree.rb`, `enhanced_tracer.rb`, and formatter files to be world-readable
+- Gem now correctly includes all files when installed (previously missing EnhancedTracer and formatters)
+
+### Added
+- Code coverage reporting with SimpleCov (99% line coverage, 84% branch coverage)
+- Codecov integration for CI/CD coverage tracking
+- Comprehensive test suite for BaseFormatter and TreeFormatter (18 new tests)
+- Coverage badge in README
+
 ## [0.3.0] - 2025-11-19
 
 ### Added

data/README.md

@@ -1,4 +1,5 @@
 [![Ruby](https://github.com/Seunadex/ruby_method_tracer/actions/workflows/main.yml/badge.svg?branch=main)](https://github.com/Seunadex/ruby_method_tracer/actions/workflows/main.yml)
+[![codecov](https://codecov.io/gh/Seunadex/ruby_method_tracer/branch/main/graph/badge.svg)](https://codecov.io/gh/Seunadex/ruby_method_tracer)
 
 # RubyMethodTracer
 
@@ -253,6 +254,16 @@ After checking out the repo, run `bin/setup` to install dependencies. Then run `
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version in `lib/ruby_method_tracer/version.rb`, and then run `bundle exec rake release`.
 
+### Code Coverage
+
+This project uses [SimpleCov](https://github.com/simplecov-ruby/simplecov) for code coverage analysis. Coverage reports are automatically generated when running tests:
+
+```bash
+bundle exec rspec
+```
+
+After running the tests, open `coverage/index.html` in your browser to view the detailed coverage report. The project maintains a minimum coverage threshold of 95% line coverage and 80% branch coverage.
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/Seunadex/ruby_method_tracer. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/Seunadex/ruby_method_tracer/blob/main/CODE_OF_CONDUCT.md).

data/lib/ruby_method_tracer/call_tree.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+module RubyMethodTracer
+  # CallTree manages the hierarchical structure of method calls,
+  # tracking parent-child relationships and call depths.
+  #
+  # It uses a stack-based approach to manage nested calls and builds
+  # a tree structure showing the complete call hierarchy.
+  class CallTree
+    attr_reader :calls, :root_calls
+
+    def initialize
+      @calls = []           # All recorded calls (flat list)
+      @call_stack = []      # Current execution stack
+      @root_calls = []      # Top-level calls (depth 0)
+      @lock = Mutex.new     # Thread safety
+    end
+
+    # Start tracking a method call
+    #
+    # @param method_name [String] The name of the method being called
+    # @return [Hash] The call record that was pushed to the stack
+    def start_call(method_name) # rubocop:disable Metrics/MethodLength
+      @lock.synchronize do
+        call_record = {
+          method_name: method_name,
+          start_time: monotonic_time,
+          depth: @call_stack.size,
+          parent: @call_stack.last,
+          children: [],
+          status: nil,
+          error: nil,
+          execution_time: nil,
+          timestamp: Time.now
+        }
+
+        # Add as child to parent if we're nested
+        @call_stack.last[:children] << call_record if @call_stack.any?
+
+        # Track root-level calls
+        @root_calls << call_record if @call_stack.empty?
+
+        @call_stack.push(call_record)
+        call_record
+      end
+    end
+
+    # End tracking a method call
+    #
+    # @param status [Symbol] :success or :error
+    # @param error [Exception, nil] The exception if status is :error
+    # @return [Hash, nil] The completed call record
+    def end_call(status = :success, error = nil)
+      @lock.synchronize do
+        return nil if @call_stack.empty?
+
+        call_record = @call_stack.pop
+        call_record[:status] = status
+        call_record[:error] = error
+        call_record[:execution_time] = monotonic_time - call_record[:start_time]
+
+        @calls << call_record
+        call_record
+      end
+    end
+
+    # Get the current call depth
+    #
+    # @return [Integer] The current nesting level
+    def current_depth
+      @lock.synchronize { @call_stack.size }
+    end
+
+    # Get call hierarchy as nested structure
+    #
+    # @return [Array<Hash>] Root calls with nested children
+    def call_hierarchy
+      @lock.synchronize { @root_calls.dup }
+    end
+
+    # Calculate statistics from recorded calls
+    #
+    # @return [Hash] Statistics including total calls, time, slowest methods, etc.
+    def statistics
+      @lock.synchronize do
+        return default_statistics if @calls.empty?
+
+        method_stats = calculate_method_stats
+
+        {
+          total_calls: @calls.size,
+          total_time: @calls.sum { |c| c[:execution_time] },
+          unique_methods: method_stats.size,
+          slowest_methods: slowest_methods(method_stats),
+          most_called_methods: most_called_methods(method_stats),
+          average_time_per_method: average_times(method_stats),
+          max_depth: @calls.map { |c| c[:depth] }.max || 0
+        }
+      end
+    end
+
+    # Clear all recorded calls and reset state
+    def clear
+      @lock.synchronize do
+        @calls.clear
+        @call_stack.clear
+        @root_calls.clear
+      end
+    end
+
+    # Check if call stack is empty (no active calls)
+    #
+    # @return [Boolean]
+    def empty?
+      @lock.synchronize { @call_stack.empty? }
+    end
+
+    private
+
+    def monotonic_time
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def default_statistics
+      {
+        total_calls: 0,
+        total_time: 0.0,
+        unique_methods: 0,
+        slowest_methods: [],
+        most_called_methods: [],
+        average_time_per_method: {},
+        max_depth: 0
+      }
+    end
+
+    def calculate_method_stats
+      method_stats = Hash.new { |h, k| h[k] = { calls: 0, total_time: 0.0, times: [] } }
+
+      @calls.each do |call|
+        stats = method_stats[call[:method_name]]
+        stats[:calls] += 1
+        stats[:total_time] += call[:execution_time]
+        stats[:times] << call[:execution_time]
+      end
+
+      method_stats
+    end
+
+    def slowest_methods(method_stats)
+      method_stats
+        .map { |name, stats| { method: name, avg_time: stats[:total_time] / stats[:calls] } }
+        .sort_by { |m| -m[:avg_time] }
+        .take(10)
+    end
+
+    def most_called_methods(method_stats)
+      method_stats
+        .map { |name, stats| { method: name, count: stats[:calls] } }
+        .sort_by { |m| -m[:count] }
+        .take(10)
+    end
+
+    def average_times(method_stats)
+      method_stats.transform_values { |stats| stats[:total_time] / stats[:calls] }
+    end
+  end
+end

data/lib/ruby_method_tracer/enhanced_tracer.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require_relative "simple_tracer"
+require_relative "call_tree"
+require_relative "formatters/tree_formatter"
+
+module RubyMethodTracer
+  # EnhancedTracer extends SimpleTracer with hierarchical call tracking
+  #
+  # In addition to the basic tracing functionality, this tracer maintains
+  # a call tree that captures parent-child relationships between method calls,
+  # enabling visualization of complex call hierarchies.
+  #
+  # Options:
+  # - All options from SimpleTracer
+  # - :track_hierarchy (Boolean): Enable call tree tracking; defaults to true
+  #
+  # Usage:
+  #   tracer = RubyMethodTracer::EnhancedTracer.new(MyClass, threshold: 0.005)
+  #   tracer.trace_method(:expensive_call)
+  #   tracer.print_tree
+  class EnhancedTracer < SimpleTracer
+    attr_reader :call_tree
+
+    def initialize(target_class, **options)
+      super
+      @call_tree = CallTree.new
+      @track_hierarchy = @options.fetch(:track_hierarchy, true)
+      @formatter = Formatters::TreeFormatter.new
+    end
+
+    def trace_method(name)
+      method_name = name.to_sym
+      visibility = method_visibility(method_name)
+      return unless visibility
+      return unless mark_wrapped?(method_name)
+
+      aliased = alias_for(method_name)
+      @target_class.send(:alias_method, aliased, method_name)
+
+      tracer = self
+      key = :__ruby_method_tracer_in_trace
+
+      # Build wrapper that tracks hierarchy
+      @target_class.define_method(method_name, &build_enhanced_wrapper(aliased, method_name, key, tracer))
+
+      @target_class.send(visibility, method_name)
+    end
+
+    # Print the call tree visualization
+    #
+    # @param options [Hash] Formatting options
+    # @option options [Boolean] :show_errors (true) Include error information
+    # @option options [Boolean] :colorize (true) Apply colors to output
+    def print_tree(options = {})
+      puts @formatter.format(@call_tree, options)
+    end
+
+    # Get call tree as string without printing
+    #
+    # @param options [Hash] Formatting options
+    # @return [String] Formatted call tree
+    def format_tree(options = {})
+      @formatter.format(@call_tree, options)
+    end
+
+    # Get enhanced results including both flat list and hierarchy
+    #
+    # @return [Hash] Results with call tree and statistics
+    def fetch_enhanced_results
+      {
+        flat_calls: fetch_results,
+        call_hierarchy: @call_tree.call_hierarchy,
+        statistics: @call_tree.statistics
+      }
+    end
+
+    # Clear both simple tracer results and call tree
+    def clear_results
+      super
+      @call_tree.clear
+    end
+
+    private
+
+    # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+    def build_enhanced_wrapper(aliased, method_name, key, tracer)
+      track_hierarchy = tracer.instance_variable_get(:@track_hierarchy)
+      # Use method-specific key to prevent only SELF-recursion, not all nested calls
+      method_key = :"#{key}_#{method_name}"
+
+      proc do |*args, **kwargs, &block|
+        if track_hierarchy
+          # Prevent only recursive calls to the SAME method
+          return __send__(aliased, *args, **kwargs, &block) if Thread.current[method_key]
+
+          Thread.current[method_key] = true
+          full_method_name = "#{tracer.instance_variable_get(:@target_class)}##{method_name}"
+
+          # Start tracking in call tree
+          tracer.call_tree.start_call(full_method_name)
+
+          start = tracer.__send__(:monotonic_time)
+          begin
+            result = __send__(aliased, *args, **kwargs, &block)
+            execution_time = tracer.__send__(:monotonic_time) - start
+
+            # Record in both places
+            tracer.__send__(:record_call, method_name, execution_time, :success)
+            tracer.call_tree.end_call(:success)
+
+            result
+          rescue StandardError => e
+            execution_time = tracer.__send__(:monotonic_time) - start
+
+            # Record in both places
+            tracer.__send__(:record_call, method_name, execution_time, :error, e)
+            tracer.call_tree.end_call(:error, e)
+
+            raise
+          ensure
+            Thread.current[method_key] = false
+          end
+        else
+          tracer.__send__(:wrap_call, method_name, key) do
+            __send__(aliased, *args, **kwargs, &block)
+          end
+        end
+      end
+    end
+    # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+
+    def default_options
+      super.merge(track_hierarchy: true)
+    end
+  end
+end

data/lib/ruby_method_tracer/formatters/base_formatter.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module RubyMethodTracer
+  module Formatters
+    # Base class for formatting trace output
+    class BaseFormatter
+      # Format timing value into human-readable string
+      #
+      # @param seconds [Float] Time in seconds
+      # @return [String] Formatted time string
+      def format_time(seconds)
+        if seconds >= 1.0
+          "#{seconds.round(3)}s"
+        elsif seconds >= 0.001
+          "#{(seconds * 1000).round(1)}ms"
+        else
+          "#{(seconds * 1_000_000).round(0)}µs"
+        end
+      end
+
+      # Apply color to text using ANSI escape codes
+      #
+      # @param text [String] Text to colorize
+      # @param color [Symbol] Color name
+      # @return [String] Colorized text
+      def colorize(text, color)
+        colors = {
+          red: "31",
+          green: "32",
+          yellow: "33",
+          blue: "34",
+          magenta: "35",
+          cyan: "36",
+          white: "37",
+          reset: "0"
+        }
+        "\e[#{colors[color]}m#{text}\e[#{colors[:reset]}m"
+      end
+
+      # Abstract method to be implemented by subclasses
+      #
+      # @param _data [Object] Data to format
+      # @raise [NotImplementedError] Must be implemented by subclass
+      def format(_data)
+        raise NotImplementedError, "#{self.class} must implement #format"
+      end
+    end
+  end
+end

data/lib/ruby_method_tracer/formatters/tree_formatter.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+require_relative "base_formatter"
+
+module RubyMethodTracer
+  module Formatters
+    # TreeFormatter generates hierarchical tree visualizations of method calls
+    class TreeFormatter < BaseFormatter
+      # Format call tree into hierarchical string representation
+      #
+      # @param call_tree [CallTree] The call tree to format
+      # @param options [Hash] Formatting options
+      # @option options [Boolean] :show_errors (true) Include error information
+      # @option options [Boolean] :colorize (true) Apply colors to output
+      # @return [String] Formatted tree visualization
+      # rubocop:disable Metrics/AbcSize
+      def format(call_tree, options = {})
+        opts = default_options.merge(options)
+        root_calls = call_tree.call_hierarchy
+
+        return "No method calls recorded.\n" if root_calls.empty?
+
+        output = []
+        output << header
+        output << separator
+
+        root_calls.each_with_index do |call, index|
+          is_last_root = index == root_calls.size - 1
+          output << format_call_node(call, "", is_last_root, opts)
+          output << "" unless is_last_root # Blank line between root calls
+        end
+
+        output << separator
+        output << format_statistics(call_tree.statistics, opts)
+
+        output.join("\n")
+      end
+      # rubocop:enable Metrics/AbcSize
+
+      private
+
+      def default_options
+        {
+          show_errors: true,
+          colorize: true
+        }
+      end
+
+      def header
+        "METHOD CALL TREE"
+      end
+
+      def separator
+        "=" * 60
+      end
+
+      # Recursively format a call node and its children
+      #
+      # @param call [Hash] Call record
+      # @param prefix [String] Current line prefix for indentation
+      # @param is_last [Boolean] Whether this is the last sibling
+      # @param opts [Hash] Formatting options
+      # @return [String] Formatted call tree section
+      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity
+      def format_call_node(call, prefix, is_last, opts)
+        lines = []
+
+        # Format the current call
+        lines << format_call_line(call, prefix, is_last, opts)
+
+        # Format error details if present
+        if call[:status] == :error && call[:error] && opts[:show_errors]
+          error_prefix = prefix + (is_last ? "    " : "│   ")
+          lines << format_error_line(call[:error], error_prefix, opts)
+        end
+
+        # Format children
+        unless call[:children].empty?
+          child_prefix = prefix + (is_last ? "    " : "│   ")
+          call[:children].each_with_index do |child, index|
+            is_last_child = index == call[:children].size - 1
+            lines << format_call_node(child, child_prefix, is_last_child, opts)
+          end
+        end
+
+        lines.join("\n")
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity
+
+      # Format a single call line
+      #
+      # @param call [Hash] Call record
+      # @param prefix [String] Current line prefix
+      # @param is_last [Boolean] Whether this is the last sibling
+      # @param opts [Hash] Formatting options
+      # @return [String] Formatted call line
+      def format_call_line(call, prefix, is_last, opts)
+        connector = is_last ? "└── " : "├── "
+        tree_part = prefix + connector
+
+        method_name = call[:method_name]
+        time_str = format_time(call[:execution_time])
+        status_indicator = call[:status] == :error ? " [ERROR]" : ""
+
+        if opts[:colorize]
+          method_name = colorize(method_name, :cyan)
+          time_str = colorize("(#{time_str})", :yellow)
+          status_indicator = colorize(status_indicator, :red) unless status_indicator.empty?
+        else
+          time_str = "(#{time_str})"
+        end
+
+        "#{tree_part}#{method_name} #{time_str}#{status_indicator}"
+      end
+
+      # Format error information
+      #
+      # @param error [Exception] The error object
+      # @param prefix [String] Current line prefix
+      # @param opts [Hash] Formatting options
+      # @return [String] Formatted error line
+      def format_error_line(error, prefix, opts)
+        error_msg = "└─ Error: #{error.class}: #{error.message}"
+        error_msg = colorize(error_msg, :red) if opts[:colorize]
+        "#{prefix}#{error_msg}"
+      end
+
+      # Format statistics summary
+      #
+      # @param stats [Hash] Statistics hash from CallTree
+      # @param opts [Hash] Formatting options
+      # @return [String] Formatted statistics
+      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      def format_statistics(stats, _opts)
+        lines = []
+        lines << "\nSTATISTICS"
+        lines << ("-" * 60)
+
+        lines << "Total Calls: #{stats[:total_calls]}"
+        lines << "Total Time: #{format_time(stats[:total_time])}"
+        lines << "Unique Methods: #{stats[:unique_methods]}"
+        lines << "Max Depth: #{stats[:max_depth]}"
+
+        unless stats[:slowest_methods].empty?
+          lines << "\nSlowest Methods (by average time):"
+          stats[:slowest_methods].take(5).each_with_index do |method, index|
+            time_str = format_time(method[:avg_time])
+            lines << "  #{index + 1}. #{method[:method]} - #{time_str}"
+          end
+        end
+
+        unless stats[:most_called_methods].empty?
+          lines << "\nMost Called Methods:"
+          stats[:most_called_methods].take(5).each_with_index do |method, index|
+            lines << "  #{index + 1}. #{method[:method]} - #{method[:count]} calls"
+          end
+        end
+
+        lines.join("\n")
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+    end
+  end
+end

data/lib/ruby_method_tracer/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RubyMethodTracer
-  VERSION = "0.3.0"
+  VERSION = "0.3.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby_method_tracer
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Seun Adekunle
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-11-19 00:00:00.000000000 Z
+date: 2025-11-22 00:00:00.000000000 Z
 dependencies: []
 description: A developer-friendly gem for tracing method calls, execution times, with
   minimal overhead.
@@ -26,6 +26,10 @@ files:
 - README.md
 - Rakefile
 - lib/ruby_method_tracer.rb
+- lib/ruby_method_tracer/call_tree.rb
+- lib/ruby_method_tracer/enhanced_tracer.rb
+- lib/ruby_method_tracer/formatters/base_formatter.rb
+- lib/ruby_method_tracer/formatters/tree_formatter.rb
 - lib/ruby_method_tracer/simple_tracer.rb
 - lib/ruby_method_tracer/version.rb
 - sig/ruby_method_tracer.rbs