bulldogger 0.1.0

data/lib/bulldogger/probe/session.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require_relative "target_resolver"
+require_relative "registry"
+require_relative "raise_tracker"
+require_relative "method_stats"
+require_relative "writer"
+
+module Bulldogger
+  module Probe
+    # One probe run: resolves and reserves its targets, builds one
+    # TracePoint per target (contract-verbs.md: "1 TracePoint can only
+    # enable one target -- can't nest-enable a targeting TracePoint"),
+    # aggregates every observed call/return into MethodStats, and
+    # writes the evidence file on finish.
+    class Session
+      def self.start(target_strings, config:, run:)
+        return nil unless config.enabled
+
+        targets = TargetResolver.resolve!(target_strings)
+        labels = targets.map(&:label)
+        Registry.reserve!(labels)
+        begin
+          new(targets: targets, config: config, run: run).enable!
+        rescue Exception # rubocop:disable Lint/RescueException
+          # A target that fails mid-enable (all targets already passed
+          # TargetResolver's own check, so this is the unlikely case --
+          # a race with the app redefining a method, say) must not
+          # leave its label stuck in Registry: that would refuse every
+          # later probe of the same target for the rest of the process.
+          Registry.release(labels)
+          raise
+        end
+      end
+
+      def self.run(target_strings, config:, run:)
+        unless config.enabled
+          # The switch being off must not stop the caller's own code
+          # from running -- only from being observed and written. See
+          # AGENTS.md: the tool must not change what the app does.
+          yield if block_given?
+          return nil
+        end
+
+        session = start(target_strings, config: config, run: run)
+        # The written path comes from session.finish, not from
+        # `begin...ensure...end`'s own value (that would be the
+        # block's return value): an ensure clause's result is
+        # discarded unless captured explicitly, and finish must still
+        # run -- and its path still be returned -- when the block
+        # raises, since a probed run that hit an exception is exactly
+        # the case where the evidence is most worth having.
+        result = nil
+        begin
+          yield
+        ensure
+          result = session.finish
+        end
+        result
+      end
+
+      def initialize(targets:, config:, run:)
+        @targets = targets
+        @config = config
+        @run = run
+        @redactor = Redactor.new(config.redact_patterns)
+        @formatter = Formatter.new(config: config, redactor: @redactor)
+        @stats = targets.each_with_object({}) do |target, hash|
+          hash[target.label] = MethodStats.new(target: target, formatter: @formatter, redactor: @redactor,
+                                                 max_samples: config.max_samples)
+        end
+        @trace_points = []
+        @started_at = Time.now.utc
+        @finished = false
+        @finish_mutex = Mutex.new
+      end
+
+      def enable!
+        RaiseTracker.instance.acquire
+        @targets.each do |target|
+          tp = build_trace_point(@stats[target.label])
+          tp.enable(target: target.unbound_method)
+          @trace_points << tp
+        end
+        self
+      rescue Exception # rubocop:disable Lint/RescueException
+        @trace_points.each(&:disable)
+        RaiseTracker.instance.release
+        raise
+      end
+
+      def finish
+        @finish_mutex.synchronize do
+          return @result_path if @finished
+
+          @finished = true
+          @trace_points.each(&:disable)
+          RaiseTracker.instance.release
+          Registry.release(@targets.map(&:label))
+          @result_path = Writer.write(run: @run, config: @config, targets: @targets, stats: @stats,
+                                       started_at: @started_at)
+        end
+      end
+
+      private
+
+      # A one-line delegation, matching every other hook in this
+      # codebase (Capture, RaiseTracker, Record::Session): the block
+      # given to TracePoint.new does no work itself, it only calls a
+      # named method. That method is what a direct unit test calls
+      # too, with a double standing in for tp, so this hook's own
+      # routing logic is covered by an ordinary test and not just by
+      # the hook actually firing (which stdlib Coverage cannot see
+      # inside).
+      def build_trace_point(stats)
+        TracePoint.new(:call, :return) { |tp| dispatch(tp, stats) }
+      end
+
+      # Delegating the block body to this named method adds one real
+      # call frame between the app's own call site and where
+      # caller_locations runs -- measured directly (the block calling
+      # a method that calls caller_locations puts one extra frame
+      # under caller_locations, versus caller_locations running
+      # straight inside the block) -- so the offset here is 3, not the
+      # 2 a bare inline block needed before this method existed.
+      # probe_caller_offset_test.rb pins this number against this
+      # exact shape.
+      #
+      # Only the first frame is ever kept (`.first` was called on a
+      # 3-frame array before this hook existed), so only 1 frame is
+      # requested here. Measured at ~300ns/call, caller_locations is
+      # the single most expensive thing this hook does -- 4-5x the
+      # cost of TracePoint's own dispatch -- and building frames this
+      # code never reads was pure waste.
+      def dispatch(tp, stats)
+        case tp.event
+        when :call
+          RaiseTracker.instance.push_checkpoint
+          caller_loc = caller_locations(3, 1)&.first
+          stats.record_call(tp, caller_loc)
+        when :return
+          # Popped before record_return, not after: even if
+          # record_return itself raises (caught below), the
+          # checkpoint stack for this fiber is already balanced, so a
+          # later call on the same fiber is never thrown off by an
+          # earlier one's formatting failure.
+          raised = RaiseTracker.instance.pop_and_raised_exit?
+          stats.record_return(tp, raised: raised)
+        end
+      rescue Exception => e # rubocop:disable Lint/RescueException
+        # The hook must never let an exception escape into the probed
+        # method's own call/return path -- doing so would replace the
+        # app's real control flow with one from inside this library.
+        # Same rule as Capture's :raise hook.
+        warn("bulldogger: probe hook failed: #{e.class}: #{e.message}") if ENV["BULLDOGGER_DEBUG"] == "1"
+      end
+    end
+  end
+end

data/lib/bulldogger/probe/target.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Bulldogger
+  module Probe
+    # One resolved probe target: the label the caller wrote
+    # ("Klass#method" / "Klass.method") paired with the UnboundMethod
+    # TracePoint#enable(target:) actually needs. Kept as a plain value
+    # object so Session and Writer never re-derive the label from the
+    # method (an UnboundMethod alone can't tell instance and singleton
+    # spelling apart) or re-run constant/method lookup after start.
+    Target = Struct.new(:label, :unbound_method)
+  end
+end

data/lib/bulldogger/probe/target_resolver.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require_relative "target"
+
+module Bulldogger
+  module Probe
+    # Turns "Klass#method" / "Klass.method" strings into Targets,
+    # failing before any TracePoint is enabled. Resolving every target
+    # up front (not lazily, on first call) is the contract's own
+    # requirement: a probe session must not let bad instrumentation
+    # surface only after the caller's code has already started
+    # running.
+    module TargetResolver
+      INSTANCE_PATTERN = /\A(.+)#(.+)\z/
+      SINGLETON_PATTERN = /\A(.+)\.(.+)\z/
+
+      module_function
+
+      def resolve!(target_strings)
+        target_strings.map { |s| resolve_one!(s) }
+      end
+
+      def resolve_one!(target_string)
+        owner_name, method_name, kind = split(target_string)
+        owner = resolve_constant!(owner_name, target_string)
+        unbound_method = resolve_unbound_method!(owner, method_name, kind, target_string)
+        assert_targetable!(unbound_method, target_string)
+        Target.new(target_string, unbound_method)
+      end
+
+      def split(target_string)
+        if (m = INSTANCE_PATTERN.match(target_string))
+          [m[1], m[2], :instance]
+        elsif (m = SINGLETON_PATTERN.match(target_string))
+          [m[1], m[2], :singleton]
+        else
+          raise ArgumentError,
+                "bulldogger: invalid probe target #{target_string.inspect} " \
+                '(expected "Klass#method" or "Klass.method")'
+        end
+      end
+
+      # const_get(name, false) at each nesting level (not a single
+      # Object.const_get("A::B")) so a wrong nested name fails with
+      # the segment that is actually missing, and so this never
+      # accidentally resolves a same-named top-level constant that
+      # const_get's own inherit-search could reach from a deeper
+      # module (the `false` argument).
+      def resolve_constant!(owner_name, target_string)
+        owner_name.split("::").reject(&:empty?).reduce(Object) do |mod, name|
+          mod.const_get(name, false)
+        end
+      rescue NameError
+        raise NameError,
+              "bulldogger: no constant #{owner_name.inspect} for probe target #{target_string.inspect}"
+      end
+
+      def resolve_unbound_method!(owner, method_name, kind, target_string)
+        if kind == :instance
+          owner.instance_method(method_name.to_sym)
+        else
+          owner.method(method_name.to_sym).unbind
+        end
+      rescue NameError
+        raise NameError, "bulldogger: no method for probe target #{target_string.inspect}"
+      end
+
+      # The only way to learn that a method is C-implemented is to
+      # actually try targeting it: UnboundMethod itself resolves fine
+      # for a C method (Array.instance_method(:push) succeeds); it is
+      # TracePoint#enable(target:) that raises ArgumentError (measured:
+      # "specified target is not supported", Array#push). The probe
+      # TracePoint built here is disabled again immediately -- its only
+      # purpose is to surface that error before any of the caller's
+      # targets go live.
+      def assert_targetable!(unbound_method, target_string)
+        probe_tp = TracePoint.new(:call) {}
+        probe_tp.enable(target: unbound_method)
+        probe_tp.disable
+      rescue ArgumentError
+        raise ArgumentError,
+              "bulldogger: probe target #{target_string.inspect} is a C-implemented method and can't be traced"
+      end
+    end
+  end
+end

data/lib/bulldogger/probe/writer.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Bulldogger
+  module Probe
+    # Writes one probe session's aggregated MethodStats as
+    # tmp/bulldogger/run-.../probe-NNN-<slug>.json.
+    #
+    # Filenames use their own "probe-NNN-" sequence, not Run#next_path
+    # (which produces plain "NNN-<slug>.json" for failure evidence):
+    # Run is owned by the base-snapshot task and not touched here, and
+    # its sequence and this one are independent counters that happen
+    # to share a directory, not a single numbering space. Run#dir is
+    # still used for the lazy, on-first-write mkdir: probe is an
+    # explicit verb (AGENTS.md), so unlike a green test suite, a
+    # session that finished is itself the request to write, and does
+    # so even if it observed zero calls.
+    module Writer
+      @sequence = 0
+      @mutex = Mutex.new
+
+      class << self
+        attr_accessor :sequence
+        attr_reader :mutex
+      end
+
+      def self.write(run:, config:, targets:, stats:, started_at:)
+        dir = run.dir
+        return nil unless dir
+
+        path = File.join(dir, format("probe-%03d-%s.json", next_sequence, slug_for(targets)))
+        File.write(path, "#{JSON.pretty_generate(payload_for(config: config, targets: targets, stats: stats,
+                                                              started_at: started_at))}\n")
+        path
+      end
+
+      def self.next_sequence
+        mutex.synchronize { self.sequence += 1 }
+      end
+
+      def self.slug_for(targets)
+        raw = targets.map(&:label).join("_")
+        raw.gsub(/[^A-Za-z0-9_-]/, "-")[0, 80]
+      end
+
+      def self.payload_for(config:, targets:, stats:, started_at:)
+        {
+          "schema_version" => 1,
+          "kind" => "probe",
+          "tool" => { "name" => "bulldogger", "version" => Bulldogger::VERSION },
+          "started_at" => started_at.strftime("%Y-%m-%dT%H:%M:%SZ"),
+          "targets" => targets.map(&:label),
+          "methods" => targets.each_with_object({}) { |t, h| h[t.label] = stats[t.label].to_h },
+          "limits" => { "max_samples" => config.max_samples, "max_value_length" => config.max_value_length }
+        }
+      end
+      private_class_method :next_sequence, :slug_for, :payload_for
+    end
+  end
+end

data/lib/bulldogger/probe.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "redactor"
+require_relative "formatter"
+require_relative "probe/session"
+require_relative "probe/comparator"
+
+module Bulldogger
+  # Targeted capture: instead of a snapshot at the moment a test fails
+  # (Capture) or a full trace of every call (Record), a probe watches
+  # one or a few named methods across many calls and reports the
+  # *shape* of what it saw -- argument and return classes, nil counts,
+  # raise-exit counts, callers -- so a coding agent can answer
+  # "what does this method actually receive and return" without
+  # reading every call site by hand.
+  #
+  # See lib/bulldogger/probe/session.rb for the mechanism: one
+  # TracePoint per target method (:call/:return, targeted -- cheap and
+  # strictly filtered) plus one shared, ref-counted pair of untargeted
+  # TracePoints (:raise/:rescue, per contract-verbs.md the only way to
+  # tell a raise-exit apart from a method that legitimately returns
+  # nil).
+  module Probe
+    def self.start(target_strings, config:, run:)
+      Session.start(target_strings, config: config, run: run)
+    end
+
+    def self.call(target_strings, config:, run:, &block)
+      Session.run(target_strings, config: config, run: run, &block)
+    end
+
+    def self.compare(path_a, path_b)
+      Comparator.compare(path_a, path_b)
+    end
+  end
+end

data/lib/bulldogger/record/session.rb

@@ -0,0 +1,334 @@
+# frozen_string_literal: true
+
+require_relative "../redactor"
+require_relative "../formatter"
+require_relative "../frame_source"
+require_relative "writer"
+
+module Bulldogger
+  module Record
+    # One recording session: a single TracePoint subscribed to
+    # :call/:return/:raise/:rescue, writing :call/:return/:raise as
+    # JSONL lines to one trace-NNN.jsonl file.
+    #
+    # :rescue is subscribed to but never written to the file -- it
+    # exists only to feed the raise-exit discriminator (see
+    # #on_return); WRITTEN_EVENTS is the actual shipped default the
+    # task report measures and docs describe.
+    class Session
+      WRITTEN_EVENTS = %w[call return raise].freeze
+
+      # A global (non-target) TracePoint is live for the entire
+      # process the instant #enable runs -- including the rest of
+      # this constructor after that line, and the entry into #stop
+      # before it disables anything. Without this filter, every
+      # session's trace opened with its own "Session#initialize
+      # returned" and "Record.start returned" lines (the latter
+      # dumping this session's own Config#inspect -- a value formatter
+      # never meant to be part of what a caller asked to observe), and
+      # closed with a "Session#stop" call line. Reusing FrameSource's
+      # already-measured skip_path_prefix (this library's own lib/
+      # directory) filters out bulldogger's own frames the same way
+      # Capture already does for :raise.
+      SKIP_PATH_PREFIX = Bulldogger::FrameSource.default_skip_path_prefix
+
+      # Where Ruby reports TracePoint's own methods as defined.
+      INTERNAL_TRACE_POINT_PATH = "<internal:trace_point>"
+
+      # sink: is an internal seam, not part of the public API a caller
+      # is meant to use. Bulldogger::Record.start never passes it; it
+      # exists only so the overhead benchmark (test/fixtures/record/
+      # bench.rb) can isolate the cost of value capture (TracePoint
+      # dispatch, Formatter, Redactor) from the JSONL write that
+      # always follows it on the real path -- there is no production
+      # code path that captures without writing, so measuring that
+      # split needs a substitute writer to exist at all. When sink is
+      # given, run_dir is never touched.
+      def initialize(config:, run_dir:, sink: nil)
+        @config = config
+        @enabled = config.enabled && !(run_dir.nil? && sink.nil?)
+        return unless @enabled
+
+        @redactor = Redactor.new(config.redact_patterns)
+        @formatter = Formatter.new(config: config, redactor: @redactor)
+        @writer = sink || Writer.new(run_dir: run_dir, header: header)
+        @mutex = Mutex.new
+        @sequence = 0
+        # Process-wide, not per-thread: it only ever needs to answer
+        # "did a raise happen between this frame's :call and its
+        # :return", and comparing the DELTA recorded at those two
+        # points (not the counter's absolute value at :return alone)
+        # makes that answer immune to an imbalance left over from
+        # before this particular frame's call started. See the
+        # contract's "raise で抜けたときの :return" note: an absolute
+        # counter would misclassify a frame if some unrelated raise
+        # elsewhere had already left the counter positive when this
+        # frame's own :call fired.
+        @raise_rescue_counter = 0
+        # One call stack per Thread. :call/:return for a given frame
+        # always fire on the same thread that made the call, so keying
+        # by Thread.current is what lets the delta comparison (and
+        # "depth") match each :return to its own :call instead of some
+        # other thread's -- a single shared stack would interleave
+        # unrelated frames from concurrent threads and pop the wrong
+        # entry.
+        @call_stacks = Hash.new { |h, k| h[k] = [] }
+        # Set just before the real TracePoint#disable call in #stop,
+        # and checked first in #handle. Without it: TracePoint#disable
+        # is itself a Ruby-level method (its own backtrace names
+        # <internal:trace_point>), so calling it while this session's
+        # TracePoint is still enabled fires one last :call/:return
+        # through this same handler before the disable takes effect --
+        # a phantom "TracePoint#disable" line at the end of every
+        # trace file (reproduced and confirmed while building this).
+        @stopping = false
+        # A Thread-local (not tp.disable) reentrancy guard. tp.disable
+        # was tried first and rejected: TracePoint's enabled flag is
+        # process-wide, so disabling it for the duration of one
+        # thread's handler silently drops every other thread's events
+        # that happen to fire in that same window -- reproduced with 4
+        # threads calling a traced method concurrently, which lost
+        # about three-quarters of the expected :call/:return events
+        # and corrupted #on_return's per-thread depth bookkeeping for
+        # the survivors. A key unique to this Session (not a fixed
+        # name) keeps two sessions -- e.g. Record.run nested inside
+        # another -- from suppressing each other's events on the same
+        # thread.
+        @reentrant_key = :"__bulldogger_record_session_#{object_id}__"
+        @trace_point = TracePoint.new(:call, :return, :raise, :rescue) { |tp| handle(tp) }
+        @trace_point.enable
+      end
+
+      # Idempotent, matching Bulldogger.start/stop and Run#finish
+      # elsewhere in this codebase: a second call must not re-close an
+      # already-closed IO (raises IOError) just because a caller
+      # defensively calls #stop from more than one place (an ensure
+      # block after an earlier explicit call, for example).
+      def stop
+        return nil unless @enabled
+        return @result_path if @stopping
+
+        @stopping = true
+        @trace_point.disable
+        @result_path = @writer.close
+      end
+
+      private
+
+      def header
+        {
+          "schema_version" => 1,
+          "kind" => "record",
+          "started_at" => Time.now.utc.strftime("%Y-%m-%dT%H:%M:%SZ"),
+          "events" => WRITTEN_EVENTS,
+          "limits" => { "max_value_length" => @config.max_value_length }
+        }
+      end
+
+      def handle(tp)
+        return if @stopping
+        # Filters out this library's own frames (Session, Writer,
+        # Formatter, Redactor all live under the same lib/ tree), so
+        # the recursion guard below only has to catch the case that
+        # filter cannot: formatting a value calls #inspect on
+        # whatever the app passed in, and an app-defined #inspect
+        # override is Ruby code outside this prefix.
+        return if tp.path&.start_with?(SKIP_PATH_PREFIX)
+        # The path filter above cannot reach TracePoint#enable itself:
+        # it is defined in Ruby's own <internal:trace_point>, not under
+        # this library's lib/. Enabling the trace point is the last
+        # thing start does, and from the second session onward in a
+        # process the previous session has already armed the mechanism,
+        # so this session's own enable call returns while tracing is
+        # live and writes a phantom event the app never made. The event
+        # is bulldogger's own machinery, which is exactly what
+        # SKIP_PATH_PREFIX exists to keep out of a trace.
+        return if tp.path == INTERNAL_TRACE_POINT_PATH
+        # Thread-local, not tp.disable (see @reentrant_key above): this
+        # only needs to stop the current thread's own call chain from
+        # recursing into itself (Formatter calling an app object's
+        # #inspect, which itself fires a new :call this same handler
+        # would otherwise try to process); it must not touch any other
+        # thread's visibility into the trace point at all.
+        return if Thread.current[@reentrant_key]
+
+        Thread.current[@reentrant_key] = true
+        begin
+          dispatch(tp)
+        ensure
+          Thread.current[@reentrant_key] = false
+        end
+      rescue Exception => e # rubocop:disable Lint/RescueException
+        # Same rule as Capture's :raise hook (contract.md): a recorder
+        # must never be the reason the traced code fails.
+        warn("bulldogger: record failed: #{e.class}: #{e.message}") if debug?
+        nil
+      end
+
+      def dispatch(tp)
+        case tp.event
+        when :call then on_call(tp)
+        when :return then on_return(tp)
+        when :raise then on_raise(tp)
+        when :rescue then on_rescue(tp)
+        end
+      end
+
+      def on_call(tp)
+        @mutex.synchronize do
+          stack = @call_stacks[Thread.current]
+          stack.push(@raise_rescue_counter)
+          @sequence += 1
+          @writer.write_event(build_call_event(tp, @sequence, stack.size))
+        end
+      end
+
+      def on_return(tp)
+        @mutex.synchronize do
+          stack = @call_stacks[Thread.current]
+          counter_at_call = stack.last
+          depth = stack.size
+          raised = !counter_at_call.nil? && (@raise_rescue_counter - counter_at_call).positive?
+          stack.pop
+          @call_stacks.delete(Thread.current) if stack.empty?
+          @sequence += 1
+          @writer.write_event(build_return_event(tp, @sequence, depth, raised))
+        end
+      end
+
+      def on_raise(tp)
+        @mutex.synchronize do
+          @raise_rescue_counter += 1
+          @sequence += 1
+          depth = @call_stacks[Thread.current].size
+          @writer.write_event(build_raise_event(tp, @sequence, depth))
+        end
+      end
+
+      # Not written to the trace (see WRITTEN_EVENTS); this only feeds
+      # the -1 half of the raise/rescue delta #on_return reads. Covers
+      # Ruby-level rescue only (Feature #19572, landed in 3.3.0) -- a
+      # C-level exception path such as Integer(s, exception: false)
+      # never fires :raise in the first place, so it cannot leave this
+      # counter unbalanced.
+      def on_rescue(_tp)
+        @mutex.synchronize { @raise_rescue_counter -= 1 }
+      end
+
+      def build_call_event(tp, seq, depth)
+        {
+          "event" => "call",
+          "seq" => seq,
+          "depth" => depth,
+          "path" => tp.path,
+          "line" => tp.lineno,
+          "method" => method_label(tp),
+          "args" => build_args(tp)
+        }
+      end
+
+      def build_return_event(tp, seq, depth, raised)
+        event = {
+          "event" => "return",
+          "seq" => seq,
+          "depth" => depth,
+          "path" => tp.path,
+          "line" => tp.lineno,
+          "method" => method_label(tp)
+        }
+        # tp.return_value raises RuntimeError on any event but :return
+        # (measured; contract-verbs.md), and reading it at all when the
+        # method actually exited via raise would report a nil the
+        # method never returned -- the exact trap this discriminator
+        # exists to avoid, so the branch below never touches it when
+        # raised is true.
+        if raised
+          event["raised"] = true
+        else
+          event["return"] = @formatter.format(tp.return_value)
+        end
+        event
+      end
+
+      def build_raise_event(tp, seq, depth)
+        {
+          "event" => "raise",
+          "seq" => seq,
+          "depth" => depth,
+          "path" => tp.path,
+          "line" => tp.lineno,
+          "method" => method_label(tp),
+          "exception" => exception_section(tp.raised_exception)
+        }
+      end
+
+      def exception_section(exception)
+        message = exception.message.to_s
+        limit = @config.max_value_length * 5
+        section = {
+          "class" => exception_class_name(exception),
+          "message" => message.length > limit ? "#{message[0, limit]}…" : message
+        }
+        if message.length > limit
+          section["message_truncated"] = true
+          section["message_original_length"] = message.length
+        end
+        section
+      end
+
+      def exception_class_name(exception)
+        exception.class.name || exception.class.to_s
+      rescue Exception # rubocop:disable Lint/RescueException
+        "Object"
+      end
+
+      # At :call, tp.binding.local_variables holds exactly the
+      # parameters -- including omitted optional/keyword ones already
+      # filled with their default (measured: an omitted `discount:`
+      # showed as nil, not absent) -- so this is the actual-arguments
+      # read the contract calls for, not a later snapshot of whatever
+      # the method body has reassigned by :return time.
+      def build_args(tp)
+        binding = tp.binding
+        return {} unless binding
+
+        tp.parameters.each_with_object({}) do |(_kind, name), args|
+          next unless name # anonymous *, **, & params carry no name to look up
+
+          args[name.to_s] = build_value_entry(name, binding)
+        end
+      end
+
+      def build_value_entry(name, binding)
+        return { "redacted" => true, "reason" => "name" } if @redactor.redact_name?(name)
+
+        @formatter.format(binding.local_variable_get(name))
+      end
+
+      # "Klass#method" for an instance method, "Klass.method" for a
+      # class/singleton method. attached_object recovers the real
+      # owner name from tp.defined_class's singleton class; without it
+      # a class method would render as "#<Class:Klass>", which a
+      # reader has no use for. No respond_to? guard: singleton_class?
+      # and attached_object are both guaranteed on every Ruby this gem
+      # accepts (>= 4.0; attached_object landed in 3.2). The rescue
+      # below covers the real runtime edge case instead --
+      # attached_object raises TypeError for a singleton class with no
+      # attached object, e.g. nil/true/false's.
+      def method_label(tp)
+        klass = tp.defined_class
+        if klass.singleton_class?
+          "#{klass.attached_object}.#{tp.method_id}"
+        else
+          "#{klass}##{tp.method_id}"
+        end
+      rescue Exception # rubocop:disable Lint/RescueException
+        tp.method_id.to_s
+      end
+
+      def debug?
+        ENV["BULLDOGGER_DEBUG"] == "1"
+      end
+    end
+  end
+end