traceologist 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c261c58ea4419254a9430d2ebabfda66ebf2ad5e8d9db9f95f3ec31d7563a26e
+  data.tar.gz: cd77fd9073de348dcec9306a3f51d1c84465e98c33dd192c30ff8bc06373a949
+SHA512:
+  metadata.gz: 3a5e166470e5df3db44bb7429d53fecc306a2058be77659129df6693108ef230ab5527cd4c2488fc9f9fa596afdc000550ea0552530bf3eeda46f0f0698653b0
+  data.tar.gz: 0ab1eeb6feede252012c4b5eb8c606b3f688f5e33d8f474881cd9cb57ae44b7970bf8631007e842edebe551ef8ea59c9591250e1adcc11a797a21d665742832d

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Koji NAKAMURA
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,134 @@
+# Traceologist
+
+Traceologist is a Ruby gem that traces method call sequences using `TracePoint`, returning a structured, human-readable log of calls, arguments, and return values.
+
+It is designed for debugging and understanding runtime behavior — drop it into any block of code and get a clear picture of what methods were called, with what arguments, and what they returned.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "traceologist"
+```
+
+Or install directly:
+
+```bash
+gem install traceologist
+```
+
+## Usage
+
+### Basic
+
+```ruby
+require "traceologist"
+
+class Order
+  def initialize(items)
+    @items = items
+  end
+
+  def total
+    @items.sum { |item| item[:price] }
+  end
+end
+
+result = Traceologist.trace_sequence(filter: "Order") do
+  order = Order.new([{ price: 100 }, { price: 250 }])
+  order.total
+end
+
+puts result
+```
+
+Output:
+
+```
+-> Order(#1)#initialize
+    items: [{:price=>100}, {:price=>250}]
+<- Order(#1)#initialize
+    => Order(#1)
+-> Order(#1)#total
+<- Order(#1)#total
+    => 350
+```
+
+### Options
+
+#### `filter:` — Limit tracing to specific classes
+
+Pass a class name prefix (or an array of prefixes) to exclude noise from the trace:
+
+```ruby
+Traceologist.trace_sequence(filter: "MyApp") { ... }
+Traceologist.trace_sequence(filter: ["MyApp::Order", "MyApp::Item"]) { ... }
+```
+
+Without a filter, **all** Ruby method calls within the block are traced.
+
+#### `depth_limit:` — Cap recursion depth (default: `20`)
+
+```ruby
+Traceologist.trace_sequence(depth_limit: 5, filter: "MyClass") { ... }
+```
+
+#### `show_location:` — Include source file and line number
+
+```ruby
+result = Traceologist.trace_sequence(filter: "MyClass", show_location: true) do
+  MyClass.new.run
+end
+```
+
+Output includes a comment on each call line:
+
+```
+-> MyClass(#1)#run # /path/to/my_class.rb:12
+```
+
+### Reading the output
+
+Each element of the returned array is a string. The lines follow this format:
+
+| Pattern | Meaning |
+|---|---|
+| `-> ClassName(#N)#method` | Method call (indented by depth) |
+| `    arg: value` | Argument name and value |
+| `<- ClassName(#N)#method` | Method return (indented by depth) |
+| `    => value` | Return value |
+
+`#N` is a stable sequence number assigned to each unique object instance within the traced block. The same object always gets the same number, making it easy to follow a single instance across many calls.
+
+Primitive values (`Integer`, `Float`, `String`, `Symbol`, `nil`, `true`, `false`) are shown with `inspect`. All other objects are shown as `ClassName(#N)`.
+
+### Writing to a file
+
+`trace_sequence` returns a `Traceologist::String` — a plain string that also supports `>>` for writing to a file:
+
+```ruby
+result = Traceologist.trace_sequence(filter: "MyClass") { MyClass.new.run }
+
+result >> "trace.txt"       # writes to file; raises if it already exists
+puts result                 # prints to stdout like any string
+```
+
+If the file already exists, `>>` raises a `RuntimeError` to avoid accidental overwrites.
+
+## Development
+
+```bash
+bin/setup       # install dependencies
+bundle exec rake test   # run tests
+bundle exec rubocop     # lint
+bin/console     # interactive prompt
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/kozy4324/traceologist.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/lib/traceologist/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Traceologist
+  VERSION = "0.1.0"
+end

data/lib/traceologist.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require_relative "traceologist/version"
+
+# Traceologist traces Ruby method call sequences using TracePoint,
+# returning a structured log of calls, arguments, and return values.
+module Traceologist
+  class Error < StandardError; end
+
+  # A String subclass returned by {trace_sequence} that supports writing to a file with `>>`.
+  class String < ::String
+    # Writes the trace to a file. Raises if the file already exists.
+    # @param path [String] destination file path
+    def >>(other)
+      raise "A file already exists!" if File.exist?(other)
+
+      File.write(other, to_s)
+    end
+  end
+
+  # Traces method call sequences within the given block using TracePoint.
+  #
+  # @param depth_limit [Integer] Maximum call depth to trace (default: 20)
+  # @param filter [String, Symbol, Array<String, Symbol>, nil] Only trace classes whose name
+  #   starts with one of these prefixes. When nil, all calls are traced.
+  # @param show_location [Boolean] Whether to include source file and line number (default: false)
+  # @yield The block of code to trace
+  # @return [Traceologist::String] The call sequence as a newline-joined string
+  #
+  # @example
+  #   result = Traceologist.trace_sequence(filter: "MyClass") { MyClass.new.run }
+  #   puts result
+  def self.trace_sequence(depth_limit: 20, filter: nil, show_location: false, &)
+    Tracer.new(depth_limit: depth_limit, filter: filter, show_location: show_location).run(&)
+  end
+
+  # @api private
+  class Tracer
+    def initialize(depth_limit:, filter:, show_location:)
+      @depth_limit = depth_limit
+      @filter = filter
+      @show_location = show_location
+      @depth = 0
+      @call_stack = []
+      @calls = []
+      @object_registry = {}.compare_by_identity
+      @next_id = 0
+    end
+
+    def run(&)
+      trace_point = TracePoint.new(:call, :return) { |event| handle(event) }
+      trace_point.enable(&)
+      Traceologist::String.new(@calls.join("\n"))
+    end
+
+    private
+
+    def handle(event)
+      assign_seq(event.self)
+      case event.event
+      when :call then on_call(event)
+      when :return then on_return(event)
+      end
+    end
+
+    def on_call(event)
+      unless matches?(event.defined_class.to_s) && @depth <= @depth_limit
+        @call_stack << false
+        return
+      end
+
+      @call_stack << true
+      @calls << call_line(event)
+      record_args(event)
+      @depth += 1
+    end
+
+    def on_return(event)
+      return unless @call_stack.pop
+
+      @depth -= 1
+      indent = "  " * @depth
+      @calls << "#{indent}<- #{label(event)}"
+      @calls << "#{indent}    => #{format_value(event.return_value)}"
+    end
+
+    def call_line(event)
+      indent = "  " * @depth
+      location = @show_location ? " # #{event.path}:#{event.lineno}" : ""
+      "#{indent}-> #{label(event)}#{location}"
+    end
+
+    def record_args(event)
+      indent = "  " * @depth
+      args = event.parameters.filter_map do |(type, name)|
+        next if name.nil? || type == :block
+
+        val = event.binding.local_variable_get(name)
+        "#{name}: #{format_value(val)}"
+      end
+      @calls << args.map { |arg| "#{indent}    #{arg}" }.join("\n") unless args.empty?
+    rescue StandardError
+      # ignore binding errors
+    end
+
+    def label(event)
+      "#{event.defined_class}(##{@object_registry[event.self]})##{event.method_id}"
+    end
+
+    def matches?(class_name)
+      @filter.nil? || Array(@filter).any? { |prefix| class_name.start_with?(prefix.to_s) }
+    end
+
+    def assign_seq(obj)
+      @object_registry[obj] ||= (@next_id += 1)
+    rescue StandardError
+      nil
+    end
+
+    def format_value(val)
+      case val
+      when Numeric, ::String, Symbol, NilClass, TrueClass, FalseClass
+        val.inspect
+      else
+        "#{val.class}(##{assign_seq(val)})"
+      end
+    end
+  end
+
+  private_constant :Tracer
+end

data/sig/traceologist.rbs

@@ -0,0 +1,4 @@
+module Traceologist
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,53 @@
+--- !ruby/object:Gem::Specification
+name: traceologist
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Koji NAKAMURA
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: |
+  Traceologist wraps a block of Ruby code with TracePoint and returns a
+  structured, human-readable log of every method call, its arguments, and
+  its return value. Useful for debugging and understanding runtime behavior.
+email:
+- kozy4324@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/traceologist.rb
+- lib/traceologist/version.rb
+- sig/traceologist.rbs
+homepage: https://github.com/kozy4324/traceologist
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/kozy4324/traceologist
+  source_code_uri: https://github.com/kozy4324/traceologist
+  changelog_uri: https://github.com/kozy4324/traceologist/releases
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Trace Ruby method call sequences with arguments and return values.
+test_files: []