start-agent-task: refactor-gems

Author: zah

.agents/codebase-insights.txt

@@ -1 +1,6 @@
-No insights yet. Please add content here and remove this line.
+When the pure Ruby recorder traces a script that holds a reference to the
+`PureRubyRecorder` instance in a local variable, the variable inspection code
+would recursively serialise the tracer's internal state. This results in an
+explosive amount of output and may appear as an infinite recursion when running
+`examples/selective_tracing_pure.rb`. To avoid this, `load_variables` now skips
+values that refer to the recorder or its `TraceRecord`.

.agents/tasks/2025/05/30-1219-refactor-gems

@@ -0,0 +1,19 @@
+A previous developer got the following task:
+
+> Make sure the functionality of both gems is usable as a library. The gem binaries
+> should just call into methods exported by the gem libraries. Make command-line
+> handling consistent between the two gems. Use class names that are derived from
+> the gem names.
+
+He made really good progress in commit d007872908d4fb5dbe862549f825eec98e7721f0, but
+he hasn't tested his code.
+
+Please test his changes and fix any issues that you find.
+
+He tried to implement one new feature:
+
+Both gem binaries now allow the standard "--" separator that specifies where
+the arguments of the executed program begin.
+
+Please add a test case that uses this notation to make sure its works correctly.
+Of course, keep the existing tests that don't use this notation.

.gitignore

@@ -14,5 +14,3 @@ pkg/
 # Offline dependency sources
 .codex/deps_src/
 .codex/internet_resources/
-
-agents-workflow/

MAINTAINERS.md

@@ -23,7 +23,7 @@ just build-extension
 
 This compiles the extension in release mode using Cargo. The resulting
 shared library is placed under
-`ext/native_tracer/target/release/` and is loaded by `gems/codetracer-ruby-recorder/lib/native_trace.rb`.
+`ext/native_tracer/target/release/` and is loaded by `gems/codetracer-ruby-recorder/lib/codetracer_ruby_recorder.rb`.
 
 ## Running tests
 

README.md

@@ -36,7 +36,7 @@ recorder.flush_trace(Dir.pwd)
 you can currently use it directly with
 
 ```bash
-ruby gems/codetracer-pure-ruby-recorder/lib/trace.rb [--out-dir DIR] <path to ruby file>
+ruby gems/codetracer-pure-ruby-recorder/bin/codetracer-pure-ruby-recorder [--out-dir DIR] <path to ruby file>
 # produces several trace json files in DIR,
 # or in `$CODETRACER_RUBY_RECORDER_OUT_DIR` if DIR is not provided.
 # Defaults to the current directory.
@@ -47,7 +47,7 @@ You can also invoke a lightweight CLI that loads the native tracer extension
 directly:
 
 ```bash
-ruby gems/codetracer-ruby-recorder/lib/native_trace.rb [--out-dir DIR] <path to ruby file>
+ruby gems/codetracer-ruby-recorder/bin/codetracer-ruby-recorder [--out-dir DIR] <path to ruby file>
 # Uses DIR or `$CODETRACER_RUBY_RECORDER_OUT_DIR` to choose where traces are saved.
 ```
 

examples/selective_tracing.rb

@@ -1,13 +1,9 @@
 #!/usr/bin/env ruby
 
-# Load the native extension only if RubyRecorder is not already available
-# (e.g., when running directly without the codetracer wrapper)
-unless defined?(RubyRecorder)
-  ext_base = File.expand_path('../gems/codetracer-ruby-recorder/ext/native_tracer/target/release/libcodetracer_ruby_recorder', __dir__)
-  require ext_base
-end
+ext_base = File.expand_path('../gems/codetracer-ruby-recorder/ext/native_tracer/target/release/libcodetracer_ruby_recorder', __dir__)
+require ext_base
 
-recorder = RubyRecorder.new
+recorder = CodeTracer::RubyRecorder.new
 
 puts 'start trace'
 recorder.disable_tracing

examples/selective_tracing_pure.rb

@@ -1,18 +1,15 @@
 #!/usr/bin/env ruby
 
-# Load the pure Ruby tracer library if RubyRecorder is not already defined
-unless defined?(RubyRecorder)
-  lib_base = File.expand_path('../gems/codetracer-pure-ruby-recorder/lib/codetracer_pure_ruby_recorder', __dir__)
-  require lib_base
-end
+lib_base = File.expand_path('../gems/codetracer-pure-ruby-recorder/lib/codetracer_pure_ruby_recorder', __dir__)
+require lib_base
 
-recorder = RubyRecorder.new
+recorder = CodeTracer::PureRubyRecorder.new
 
 puts 'start trace'
-recorder.disable_tracing
+recorder.stop
 puts 'this will not be traced'
-recorder.enable_tracing
+recorder.start
 puts 'this will be traced'
-recorder.disable_tracing
+recorder.stop
 puts 'tracing disabled'
 recorder.flush_trace(Dir.pwd)

gems/codetracer-pure-ruby-recorder/bin/codetracer-pure-ruby-recorder

@@ -1,4 +1,9 @@
 #!/usr/bin/env ruby
-require 'rbconfig'
-script = File.expand_path('../lib/trace.rb', __dir__)
-exec RbConfig.ruby, script, *ARGV
+# SPDX-License-Identifier: MIT
+# CLI for the pure Ruby tracer
+
+lib_dir = File.expand_path('../lib', __dir__)
+$LOAD_PATH.unshift(lib_dir) unless $LOAD_PATH.include?(lib_dir)
+require 'codetracer_pure_ruby_recorder'
+
+exit CodeTracer::PureRubyRecorder.parse_argv_and_trace_ruby_file(ARGV)

gems/codetracer-pure-ruby-recorder/lib/codetracer/kernel_patches.rb

@@ -1,6 +1,6 @@
 # SPDX-License-Identifier: MIT
 
-module Codetracer
+module CodeTracer
   module KernelPatches
     @@tracers = []
 
@@ -54,10 +54,6 @@ def self.uninstall(tracer)
           alias_method :p, :codetracer_original_p
           alias_method :puts, :codetracer_original_puts
           alias_method :print, :codetracer_original_print
-
-          remove_method :codetracer_original_p
-          remove_method :codetracer_original_puts
-          remove_method :codetracer_original_print
         end
       end
     end