ruby_method_tracer 0.4.0 → 0.5.0

data/sig/ruby_method_tracer.rbs

@@ -1,4 +1,213 @@
 module RubyMethodTracer
   VERSION: String
-  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+
+  class Error < StandardError
+  end
+
+  type visibility = :public | :protected | :private
+  type status = :success | :error | :incomplete
+  type export_format = :json | :flat | :tree
+
+  type call_record = {
+    method_name: String,
+    execution_time: Float,
+    status: status,
+    error: Exception?,
+    timestamp: Time
+  }
+
+  type tree_node = {
+    method_name: String,
+    start_time: Float,
+    depth: Integer,
+    children: Array[tree_node],
+    status: status?,
+    error: Exception?,
+    execution_time: Float?,
+    timestamp: Time
+  }
+
+  type results = {
+    total_calls: Integer,
+    total_time: Float,
+    calls: Array[call_record]
+  }
+
+  type statistics = {
+    total_calls: Integer,
+    total_time: Float,
+    unique_methods: Integer,
+    slowest_methods: Array[{ method: String, avg_time: Float }],
+    most_called_methods: Array[{ method: String, count: Integer }],
+    average_time_per_method: Hash[String, Float],
+    max_depth: Integer
+  }
+
+  self.@configuration: Configuration
+
+  def self.configuration: () -> Configuration
+  def self.configure: () { (Configuration) -> void } -> Configuration
+                    | () -> Configuration
+  def self.reset_configuration!: () -> Configuration
+  def self.included: (Module) -> void
+
+  module ClassMethods
+    def trace_methods: (*Symbol | String, **untyped) -> SimpleTracer
+    def trace_class_methods: (*Symbol | String, **untyped) -> SimpleTracer
+  end
+
+  class Configuration
+    attr_accessor threshold: Float
+    attr_accessor auto_output: bool
+    attr_accessor max_calls: Integer
+    attr_accessor logger: Logger?
+    attr_accessor track_hierarchy: bool
+
+    def initialize: () -> void
+    def reset!: () -> Configuration
+    def to_h: () -> Hash[Symbol, untyped]
+  end
+
+  module Exportable
+    def render: (?format: export_format, **untyped) -> String
+    def export: (String | _ToS, ?format: export_format, **untyped) -> String
+
+    private
+
+    def build_formatter: (export_format | String) -> Formatters::BaseFormatter
+    def write_export: (String, String) -> String
+    def validate_export_path: (String | _ToS) -> String
+    def report_source: () -> untyped
+  end
+
+  module Wrapper
+    OMITTED: Object
+
+    def self.install: (Module, Symbol, Symbol, Symbol) -> Symbol
+
+    class Signature
+      def initialize: (Array[[Symbol, Symbol?]] | Array[[Symbol]]) -> void
+      def declaration: () -> String
+      def setup: () -> String
+      def forward: (Symbol) -> String
+    end
+  end
+
+  class SimpleTracer
+    include Exportable
+
+    @target_class: Module
+    @options: Hash[Symbol, untyped]
+    @calls: Array[call_record]
+    @lock: Thread::Mutex
+    @wrapped_methods: Hash[Symbol, visibility]
+    @qualified_names: Hash[Symbol, String]
+    @logger: Logger
+    @tracer_key: Symbol
+    @accessor: Symbol
+    @accessor_defined: bool?
+    @formatter: Formatters::BaseFormatter
+
+    def initialize: (Module, **untyped) -> void
+    def trace_method: (Symbol | String) -> bool
+    def untrace_method: (Symbol | String) -> bool
+    def untrace_all: () -> Array[Symbol]
+    def record_call: (Symbol, Float, status, ?Exception?) -> void
+    def fetch_results: () -> results
+    def clear_results: () -> void
+
+    private
+
+    def default_options: () -> Hash[Symbol, untyped]
+    def method_visibility: (Symbol) -> visibility?
+    def install_wrapper: (Symbol, visibility) -> void
+    def define_accessor: () -> void
+    def already_traced?: (Symbol) -> bool
+    def missing_method: (Symbol) -> bool
+    def qualified_name: (Symbol) -> String
+    def alias_for: (Symbol) -> Symbol
+    def dispatch: (Symbol) { () -> untyped } -> untyped
+    def wrap_call: (Symbol, Symbol) { () -> untyped } -> untyped
+    def monotonic_time: () -> Float
+    def output_call: (call_record) -> void
+    def status_label: (status) -> String
+    def format_time: (Float) -> String
+    def colorize: (String, Symbol) -> String
+  end
+
+  class EnhancedTracer < SimpleTracer
+    attr_reader call_tree: CallTree
+
+    @track_hierarchy: bool
+    @method_keys: Hash[Symbol, Symbol]
+
+    def initialize: (Module, **untyped) -> void
+    def print_tree: (?Hash[Symbol, untyped]) -> void
+    def format_tree: (?Hash[Symbol, untyped]) -> String
+    def fetch_enhanced_results: () -> {
+      flat_calls: results,
+      call_hierarchy: Array[tree_node],
+      statistics: statistics
+    }
+
+    private
+
+    def run_with_hierarchy: (Symbol, Symbol, ^() -> untyped) -> untyped
+  end
+
+  class CallTree
+    DEFAULT_MAX_CALLS: Integer
+
+    attr_reader calls: Array[tree_node]
+    attr_reader root_calls: Array[tree_node]
+
+    @threshold: Float
+    @max_calls: Integer
+    @lock: Thread::Mutex
+    @thread_key: Symbol
+
+    def initialize: (?threshold: Float, ?max_calls: Integer) -> void
+    def start_call: (String) -> tree_node
+    def end_call: (?status, ?Exception?) -> tree_node?
+    def current_depth: () -> Integer
+    def call_hierarchy: () -> Array[tree_node]
+    def statistics: () -> statistics
+    def clear: () -> void
+    def empty?: () -> bool
+
+    private
+
+    def discardable?: (tree_node) -> bool
+    def discard: (tree_node, tree_node?) -> nil
+    def retain: (tree_node) -> tree_node
+    def thread_call_stack: () -> Array[tree_node]
+    def monotonic_time: () -> Float
+    def default_statistics: () -> statistics
+    def calculate_method_stats: () -> Hash[String, { calls: Integer, total_time: Float, times: Array[Float] }]
+    def slowest_methods: (Hash[String, untyped]) -> Array[{ method: String, avg_time: Float }]
+    def most_called_methods: (Hash[String, untyped]) -> Array[{ method: String, count: Integer }]
+    def average_times: (Hash[String, untyped]) -> Hash[String, Float]
+  end
+
+  module Formatters
+    class BaseFormatter
+      def format_time: (Float) -> String
+      def colorize: (String, Symbol) -> String
+      def format: (untyped, ?Hash[Symbol, untyped]) -> String
+    end
+
+    class TreeFormatter < BaseFormatter
+      def format: (CallTree, ?Hash[Symbol, untyped]) -> String
+    end
+
+    class JsonFormatter < BaseFormatter
+      def format: (CallTree | results, ?Hash[Symbol, untyped]) -> String
+    end
+
+    class FlatFormatter < BaseFormatter
+      HEADERS: Array[String]
+
+      def format: (CallTree | results, ?Hash[Symbol, untyped]) -> String
+    end
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_method_tracer
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Seun Adekunle
@@ -17,16 +17,13 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".rspec"
-- ".rubocop.yml"
 - CHANGELOG.md
-- CLAUDE.md
 - CODE_OF_CONDUCT.md
 - LICENSE.txt
 - README.md
-- Rakefile
 - lib/ruby_method_tracer.rb
 - lib/ruby_method_tracer/call_tree.rb
+- lib/ruby_method_tracer/call_tree_statistics.rb
 - lib/ruby_method_tracer/configuration.rb
 - lib/ruby_method_tracer/enhanced_tracer.rb
 - lib/ruby_method_tracer/exportable.rb
@@ -36,6 +33,7 @@ files:
 - lib/ruby_method_tracer/formatters/tree_formatter.rb
 - lib/ruby_method_tracer/simple_tracer.rb
 - lib/ruby_method_tracer/version.rb
+- lib/ruby_method_tracer/wrapper.rb
 - sig/ruby_method_tracer.rbs
 homepage: https://github.com/Seunadex/ruby_method_tracer
 licenses:

data/.rspec

@@ -1,3 +0,0 @@
---format documentation
---color
---require spec_helper

data/.rubocop.yml

@@ -1,27 +0,0 @@
-plugins:
-  - rubocop-rspec
-
-AllCops:
-  TargetRubyVersion: 3.0
-  SuggestExtensions: false
-  NewCops: enable
-  Exclude:
-    - 'examples/**/*'
-    - 'vendor/**/*'
-
-Style/StringLiterals:
-  EnforcedStyle: double_quotes
-
-Style/StringLiteralsInInterpolation:
-  EnforcedStyle: double_quotes
-
-Metrics/MethodLength:
-  Max: 15
-Metrics/ClassLength:
-  Max: 120
-
-RSpec/MultipleExpectations:
-  Max: 15
-
-RSpec/ExampleLength:
-  Max: 15

data/CLAUDE.md

@@ -1,61 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Commands
-
-```bash
-bundle exec rspec          # Run all tests (also generates coverage report in coverage/)
-bundle exec rubocop        # Lint
-bundle exec rake           # Run both spec and rubocop (default task)
-
-# Run a single spec file
-bundle exec rspec spec/ruby_method_tracer/simple_tracer_spec.rb
-
-# Run a specific example by description
-bundle exec rspec spec/ruby_method_tracer/simple_tracer_spec.rb -e "records call details"
-
-# Install gem locally for manual testing
-bundle exec rake install
-
-# Release: bump version in lib/ruby_method_tracer/version.rb, then:
-bundle exec rake release
-```
-
-## Commit conventions
-
-- Do NOT add a `Co-authored-by:` trailer (or any "Generated with"/agent attribution) to commit messages.
-
-## Architecture
-
-The gem provides two ways to trace methods:
-
-1. **Mixin API** — `include RubyMethodTracer` in a class, then call `trace_methods(:method_name, **opts)` at the class level. This creates a `SimpleTracer` internally and is the simplest entry point.
-
-2. **Direct tracer API** — instantiate `SimpleTracer` or `EnhancedTracer` directly for programmatic access to results.
-
-### Tracing mechanism (SimpleTracer)
-
-`SimpleTracer#trace_method` wraps a method by:
-1. Detecting visibility (public/protected/private) via `method_defined?` etc.
-2. Aliasing the original to `__ruby_method_tracer_original_<name>__`
-3. Redefining the method with a proc that times the call and delegates to the alias
-4. Restoring the original visibility
-
-The wrapper uses `Thread.current[:__ruby_method_tracer_in_trace]` as a reentrancy flag to avoid recursive double-recording. Kwargs are forwarded conditionally (`kwargs.empty?` check) to stay compatible with Ruby 3.x.
-
-Results are stored in `@calls` (an Array) guarded by a `Mutex`. The `max_calls` option enforces a sliding window by `shift`-ing the oldest entry.
-
-### EnhancedTracer
-
-Inherits from `SimpleTracer` and adds call-tree tracking via `CallTree`. It overrides `trace_method` to use a per-method reentrancy key (`__ruby_method_tracer_in_trace_<method_name>`) so that *different* wrapped methods can nest inside each other (unlike `SimpleTracer` which blocks all nesting).
-
-### CallTree
-
-Stack-based hierarchy tracker. `start_call` pushes a record (with a `parent` pointer and `children` array) onto `@call_stack`; `end_call` pops it, fills timing/status, and appends to the flat `@calls` list. Root-level calls (depth 0) are also collected in `@root_calls` for tree rendering.
-
-### Formatters
-
-`Formatters::BaseFormatter` — abstract base providing `format_time` and `colorize` (ANSI).
-
-`Formatters::TreeFormatter < BaseFormatter` — renders a `CallTree` as an ASCII tree with `└──`/`├──` connectors, then appends a statistics block (slowest methods, most-called methods).

data/Rakefile

@@ -1,12 +0,0 @@
-# frozen_string_literal: true
-
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
-
-RSpec::Core::RakeTask.new(:spec)
-
-require "rubocop/rake_task"
-
-RuboCop::RakeTask.new
-
-task default: %i[spec rubocop]