bulldogger 0.1.0

data/lib/bulldogger/probe/bucket.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Bulldogger
+  module Probe
+    # One params[name]/returns aggregate: a running tally of observed
+    # classes and nil-ness (updated on every call), plus a bounded,
+    # fully-serialized sample of the first max_samples values.
+    #
+    # Tally and sample are deliberately split: contract-verbs.md
+    # measured full serialization at ~24us/event, which would blow the
+    # probe overhead budget on a call-dense target if it ran on every
+    # call. Class name and nil? never touch #inspect, so the tally
+    # stays cheap regardless of how many calls a session sees.
+    class Bucket
+      def initialize(formatter:, max_samples:, redacted_name: false)
+        @formatter = formatter
+        @max_samples = max_samples
+        @redacted_name = redacted_name
+        @classes = Hash.new(0)
+        @nil_count = 0
+        @samples = []
+        @count = 0
+      end
+
+      def record(value)
+        @count += 1
+        @classes[safe_class_name(value)] += 1
+        @nil_count += 1 if value.nil?
+        @samples << sample_for(value) if @samples.size < @max_samples
+      end
+
+      def to_h
+        h = { "classes" => @classes, "nil_count" => @nil_count, "samples" => @samples }
+        omitted = @count - @samples.size
+        # Present only when something was actually cut, so a reader
+        # can trust its absence -- the same rule contract.md applies
+        # to frames_omitted/locals_omitted.
+        h["samples_omitted"] = omitted if omitted.positive?
+        h
+      end
+
+      # Folds another Bucket's tally into this one. This is the
+      # finish-time merge step for thread-local aggregation: each
+      # thread records into its own Bucket with no lock, and totals
+      # are combined once, in one place, instead of every call taking
+      # a Mutex to update a single shared Bucket.
+      #
+      # Samples are re-capped at @max_samples here too: each
+      # thread-local Bucket already capped its own samples
+      # independently, so without this cap a target hit by N threads
+      # could publish up to N * max_samples samples, silently
+      # widening the documented limit just because more than one
+      # thread happened to record some of the calls.
+      def merge!(other)
+        @count += other.count
+        other.classes.each { |klass, n| @classes[klass] += n }
+        @nil_count += other.nil_count
+        other.samples.each do |sample|
+          break if @samples.size >= @max_samples
+
+          @samples << sample
+        end
+      end
+
+      protected
+
+      attr_reader :count, :classes, :nil_count, :samples
+
+      private
+
+      # Redaction gates on the parameter *name*, decided once at
+      # Bucket construction, never on the value: this bucket's caller
+      # (MethodStats) already checked the name against redact_patterns
+      # before a single value was ever inspected, matching Redactor's
+      # own rule of checking the name before touching the value.
+      def sample_for(value)
+        return { "redacted" => true, "reason" => "name" } if @redacted_name
+
+        @formatter.format(value)
+      end
+
+      def safe_class_name(value)
+        klass = value.class
+        klass.respond_to?(:name) ? (klass.name || klass.to_s) : klass.to_s
+      rescue Exception # rubocop:disable Lint/RescueException
+        "Object"
+      end
+    end
+  end
+end

data/lib/bulldogger/probe/comparator.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Bulldogger
+  module Probe
+    # Compares two probe evidence files for behavior-preservation:
+    # "did this refactor change what the probed methods actually do."
+    #
+    # Compares *shape* (classes seen, nil_count, raised_exits, calls,
+    # the set of callers, parameters), not raw sample values, because
+    # the default `inspect` embeds an object's memory address (e.g.
+    # `#<Order:0x000000012a>`), so two probes of *identical*,
+    # unchanged code would otherwise report differences on every run.
+    # Samples are still diffed as a secondary signal, but only after
+    # normalizing `0x[0-9a-f]+` out of them for exactly this reason.
+    module Comparator
+      HEX_ADDRESS = /0x[0-9a-f]+/i
+
+      module_function
+
+      def compare(path_a, path_b)
+        a = JSON.parse(File.read(path_a))
+        b = JSON.parse(File.read(path_b))
+        differences = []
+        compare_methods(a["methods"] || {}, b["methods"] || {}, differences)
+        { "identical" => differences.empty?, "differences" => differences }
+      end
+
+      def compare_methods(methods_a, methods_b, differences)
+        (methods_a.keys | methods_b.keys).each do |label|
+          ma = methods_a[label]
+          mb = methods_b[label]
+          if ma.nil? || mb.nil?
+            differences << "#{label}: only present in #{ma.nil? ? 'b' : 'a'}"
+            next
+          end
+
+          compare_method(label, ma, mb, differences)
+        end
+      end
+
+      def compare_method(label, ma, mb, differences)
+        add_diff(differences, label, "calls", ma["calls"], mb["calls"])
+        add_diff(differences, label, "raised_exits", ma["raised_exits"], mb["raised_exits"])
+        add_diff(differences, label, "parameters", ma["parameters"], mb["parameters"])
+        add_diff(differences, label, "raised", ma["raised"], mb["raised"])
+        # Set only, not counts: contract-verbs.md compares "the set of
+        # callers", not how many times each one fired.
+        add_diff(differences, label, "callers", (ma["callers"] || {}).keys.sort, (mb["callers"] || {}).keys.sort)
+        compare_bucket("#{label}.returns", ma["returns"], mb["returns"], differences)
+        compare_params(label, ma["params"] || {}, mb["params"] || {}, differences)
+      end
+
+      def compare_params(label, params_a, params_b, differences)
+        (params_a.keys | params_b.keys).each do |name|
+          compare_bucket("#{label} param #{name}", params_a[name], params_b[name], differences)
+        end
+      end
+
+      def compare_bucket(prefix, bucket_a, bucket_b, differences)
+        bucket_a ||= {}
+        bucket_b ||= {}
+        add_diff(differences, prefix, "classes", bucket_a["classes"], bucket_b["classes"])
+        add_diff(differences, prefix, "nil_count", bucket_a["nil_count"], bucket_b["nil_count"])
+        compare_samples(prefix, bucket_a["samples"] || [], bucket_b["samples"] || [], differences)
+      end
+
+      def compare_samples(prefix, samples_a, samples_b, differences)
+        normalized_a = normalize_samples(samples_a)
+        normalized_b = normalize_samples(samples_b)
+        return if normalized_a == normalized_b
+
+        differences << "#{prefix}.samples changed (after normalizing object addresses): " \
+                        "a=#{normalized_a.inspect} b=#{normalized_b.inspect}"
+      end
+
+      def normalize_samples(samples)
+        samples.map do |sample|
+          next sample unless sample.is_a?(Hash) && sample["value"].is_a?(String)
+
+          sample.merge("value" => sample["value"].gsub(HEX_ADDRESS, "0x…"))
+        end
+      end
+
+      def add_diff(differences, label, field, value_a, value_b)
+        return if value_a == value_b
+
+        differences << "#{label}.#{field} changed: a=#{value_a.inspect} b=#{value_b.inspect}"
+      end
+      private_class_method :compare_methods, :compare_method, :compare_params, :compare_bucket,
+                            :compare_samples, :normalize_samples, :add_diff
+    end
+  end
+end

data/lib/bulldogger/probe/method_stats.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+require_relative "bucket"
+
+module Bulldogger
+  module Probe
+    # Aggregates every :call/:return pair observed for one probe
+    # target into the "methods"[label] shape the evidence JSON
+    # publishes: call count, per-parameter and return-value shape, the
+    # raise-exit count, and the set of call sites.
+    #
+    # record_call/record_return take no lock: each caller writes only
+    # into its own ThreadLocal (below), reached through Thread.current[]
+    # -- fiber-local, like RaiseTracker's own storage, so two fibers on
+    # the same OS thread still get separate slots -- keyed uniquely to
+    # this MethodStats instance, so two threads calling the same probed
+    # method concurrently never touch the same mutable state. A per-call
+    # Mutex#synchronize was measured to be on the hot path for every
+    # single call and return; a fiber only pays a lock once -- the first
+    # time it is ever seen by this target, to register its ThreadLocal
+    # in @locals -- and #to_h folds every one of them into the published
+    # totals exactly once, at finish time.
+    class MethodStats
+      # One fiber's own, lock-free view of this target. Merged into
+      # the instance's published totals by #merge_local, once, in
+      # #to_h.
+      ThreadLocal = Struct.new(:calls, :raised_exits, :param_buckets, :returns, :raised, :callers)
+
+      def initialize(target:, formatter:, redactor:, max_samples:)
+        @formatter = formatter
+        @redactor = redactor
+        @max_samples = max_samples
+        @parameters = declared_parameters(target.unbound_method)
+
+        @calls = 0
+        @raised_exits = 0
+        @param_buckets = build_param_buckets
+        @returns = new_returns_bucket
+        @raised = Hash.new(0)
+        # key => [count, one representative Thread::Backtrace::Location].
+        # One Hash, not two: a second hash keyed the same way would be
+        # a second lookup on every single call for no benefit -- see
+        # #record_caller.
+        @callers = {}
+
+        # Unique per instance (not a fixed name): two targets probed
+        # in the same session must not share one thread-local slot.
+        @thread_key = :"bulldogger_probe_method_stats_#{object_id}"
+        @locals = []
+        @locals_mutex = Mutex.new
+        @merge_mutex = Mutex.new
+        @merged = false
+      end
+
+      def record_call(tp, caller_location)
+        local = thread_local
+        local.calls += 1
+        record_param_samples(local, tp.binding)
+        record_caller(local, caller_location)
+      end
+
+      # raised: true means contract-verbs.md's raise-exit discriminator
+      # fired for this return -- this call must not be counted as a
+      # nil return (that would fabricate a "returned nil" the method
+      # never actually did), so it updates the thread-local @raised
+      # instead of @returns and never touches the returns bucket at
+      # all.
+      def record_return(tp, raised:)
+        local = thread_local
+        if raised
+          local.raised_exits += 1
+          klass = RaiseTracker.instance.current_exception_class_name || "Object"
+          local.raised[klass] += 1
+        else
+          local.returns.record(tp.return_value)
+        end
+      end
+
+      def to_h
+        merge!
+        {
+          "calls" => @calls,
+          "raised_exits" => @raised_exits,
+          "parameters" => @parameters,
+          "params" => params_to_h,
+          "returns" => @returns.to_h,
+          "raised" => @raised,
+          "callers" => callers_to_h
+        }
+      end
+
+      private
+
+      # UnboundMethod#parameters is declared, static shape -- computed
+      # once here, not derived from tp.parameters per call, since it
+      # cannot change between calls and re-deriving it every time would
+      # only add cost with no new information.
+      def declared_parameters(unbound_method)
+        unbound_method.parameters.map { |kind, name| [kind.to_s, name&.to_s] }
+      end
+
+      def build_param_buckets
+        @parameters.each_with_object({}) do |(_kind, name), buckets|
+          next if name.nil? # anonymous *, **, or & has no bindable local to sample
+
+          buckets[name] = Bucket.new(formatter: @formatter, max_samples: @max_samples,
+                                      redacted_name: @redactor.redact_name?(name))
+        end
+      end
+
+      def new_returns_bucket
+        Bucket.new(formatter: @formatter, max_samples: @max_samples)
+      end
+
+      # Lazily creates and registers this fiber's ThreadLocal on
+      # first touch. @locals_mutex is taken only here -- once per
+      # fiber per target, not once per call -- to append to the
+      # shared registry that #merge! later reads.
+      def thread_local
+        Thread.current[@thread_key] ||= begin
+          local = ThreadLocal.new(0, 0, build_param_buckets, new_returns_bucket, Hash.new(0), {})
+          @locals_mutex.synchronize { @locals << local }
+          local
+        end
+      end
+
+      def record_param_samples(local, binding)
+        local.param_buckets.each do |name, bucket|
+          bucket.record(binding.local_variable_get(name.to_sym))
+        end
+      end
+
+      # Tallies by a "path:lineno" String built from two cheap
+      # attribute reads, not by Location#to_s (which additionally
+      # resolves and formats a method label on every single call).
+      # Measured directly: this key plus one Hash lookup costs about
+      # half of the old to_s-keyed lookup. An Array key ([path,
+      # lineno]) was tried first and measured *slower* than the
+      # to_s baseline it was meant to beat -- Array#hash and #eql?
+      # walk and hash every element on every lookup, so a compound
+      # object is not automatically a cheap Hash key. A String is.
+      #
+      # One Hash lookup, not two: the value is a mutable [count,
+      # location] pair, so an existing entry is updated in place
+      # (cheap, no second Hash op) and only a first-time key pays for
+      # a Hash write. The full "path:line:in 'label'" String -- what
+      # the evidence actually publishes -- is built from the stored
+      # Location at most once per distinct call site, in
+      # #callers_to_h, not once per call.
+      def record_caller(local, caller_location)
+        return unless caller_location
+
+        key = "#{caller_location.path}:#{caller_location.lineno}"
+        entry = local.callers[key]
+        if entry
+          entry[0] += 1
+        else
+          local.callers[key] = [1, caller_location]
+        end
+      end
+
+      # Runs once, the first time #to_h is called: folds every
+      # fiber's ThreadLocal into the published totals under
+      # @merge_mutex, so #to_h itself can be called more than once
+      # (Writer calls it exactly once per target today) without
+      # double-counting.
+      def merge!
+        return if @merged
+
+        @merge_mutex.synchronize do
+          return if @merged
+
+          # Snapshot under @locals_mutex, then merge outside it: a
+          # fiber could still be registering its own ThreadLocal
+          # (the append in #thread_local) concurrently with finish, so
+          # the read of @locals itself needs the same lock the writer
+          # uses, even though the per-call recording above never does.
+          locals = @locals_mutex.synchronize { @locals.dup }
+          locals.each { |local| merge_local(local) }
+          @merged = true
+        end
+      end
+
+      def merge_local(local)
+        @calls += local.calls
+        @raised_exits += local.raised_exits
+        local.param_buckets.each { |name, bucket| @param_buckets[name].merge!(bucket) }
+        @returns.merge!(local.returns)
+        local.raised.each { |klass, count| @raised[klass] += count }
+        local.callers.each do |key, (count, location)|
+          entry = @callers[key]
+          if entry
+            entry[0] += count
+          else
+            @callers[key] = [count, location]
+          end
+        end
+      end
+
+      def params_to_h
+        @param_buckets.transform_values(&:to_h)
+      end
+
+      # Location#to_s (the "path:line:in 'label'" format the evidence
+      # publishes) runs here, once per distinct call site total across
+      # every fiber -- not once per call, which is what made this the
+      # single most expensive part of the hook before this task.
+      def callers_to_h
+        @callers.each_with_object({}) do |(_key, (count, location)), result|
+          result[location.to_s] = count
+        end
+      end
+    end
+  end
+end

data/lib/bulldogger/probe/raise_tracker.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module Bulldogger
+  module Probe
+    # Tells a probed method's normal return apart from a raise-exit.
+    # `:call`/`:return` can be targeted to one method, but `:raise`
+    # cannot (measured in contract-verbs.md): it fires globally, for
+    # every exception in the process. Distinguishing "returned nil"
+    # from "exited by raising" needs this second, global signal,
+    # correlated with each targeted call through the checkpoint below.
+    #
+    # Mechanism (contract-verbs.md, measured on ruby 4.0.6): a global
+    # counter that a `:raise` TracePoint increments and a `:rescue`
+    # TracePoint decrements. `:call` records the counter's value; at
+    # `:return`, a *positive delta* from that recorded value means an
+    # exception passed through this frame's unwind between the two
+    # events, because the caller's own `:rescue` fires only after
+    # `:return`, so the counter is still unbalanced at `:return` time.
+    #
+    # Delta, not the absolute counter: an absolute counter left
+    # unbalanced by a raise from *before* this call started (e.g. one
+    # whose `:rescue` fires after this session already released the
+    # tracker) would poison every later call on the same fiber. A
+    # delta only asks "did the counter move during *this* call", so a
+    # pre-existing imbalance cannot produce a false positive.
+    #
+    # Counter and checkpoint stack are fiber-local (Thread.current[]),
+    # not a single shared integer: a fiber's call stack is private to
+    # that fiber, and only one exception can be unwinding through a
+    # given fiber's stack at a time, so a fiber-local counter can
+    # never be perturbed by an unrelated raise on another fiber or
+    # thread. A single shared counter would not have that guarantee.
+    #
+    # `:rescue` requires ruby >= 3.3.0 (Feature #19572); this gem's
+    # required_ruby_version is >= 4.0, so no degrade path is needed
+    # here. `:rescue` only fires for Ruby-level `rescue` (ruby's own
+    # NEWS-3.3.0.md); a raise fully handled inside C code (measured:
+    # `Integer(s, exception: false)`) never fires `:raise` either, so
+    # it cannot unbalance the counter in the first place.
+    class RaiseTracker
+      COUNTER_KEY = :bulldogger_probe_raise_counter
+      STACK_KEY = :bulldogger_probe_raise_checkpoints
+      CLASS_KEY = :bulldogger_probe_raise_class
+
+      def self.instance
+        @instance ||= new
+      end
+
+      def initialize
+        @mutex = Mutex.new
+        @refcount = 0
+        @raise_tp = nil
+        @rescue_tp = nil
+      end
+
+      # Ref-counted: multiple probe sessions can be active at once
+      # (different targets, or nested probe calls) and all of them
+      # need this same pair of TracePoints running, but each pays only
+      # its own targeted :call/:return cost -- the untargeted :raise/
+      # :rescue subscription is shared, not duplicated per session.
+      def acquire
+        @mutex.synchronize do
+          @refcount += 1
+          next unless @refcount == 1
+
+          @raise_tp = TracePoint.new(:raise) { |tp| on_raise(tp) }
+          @rescue_tp = TracePoint.new(:rescue) { on_rescue }
+          @raise_tp.enable
+          @rescue_tp.enable
+        end
+      end
+
+      def release
+        @mutex.synchronize do
+          @refcount -= 1
+          next if @refcount.positive?
+
+          @raise_tp&.disable
+          @rescue_tp&.disable
+          @raise_tp = nil
+          @rescue_tp = nil
+        end
+      end
+
+      # Call at :call time, before any work that could raise inside
+      # the hook itself -- a cheap Array#push that must not be skipped,
+      # or the matching pop_and_raised_exit? at :return would read the
+      # wrong checkpoint and desynchronize every later call on this
+      # fiber.
+      def push_checkpoint
+        (Thread.current[STACK_KEY] ||= []) << counter
+      end
+
+      # Call at :return time. Pops the checkpoint pushed by the
+      # matching push_checkpoint (calls on one fiber nest properly, so
+      # a plain stack -- not a per-target slot -- keeps recursive and
+      # interleaved targets correctly paired) and reports whether the
+      # counter moved since that call started.
+      def pop_and_raised_exit?
+        stack = Thread.current[STACK_KEY]
+        checkpoint = stack && !stack.empty? ? stack.pop : 0
+        counter > checkpoint
+      end
+
+      # Only meaningful right after pop_and_raised_exit? returned
+      # true: the class of the most recent :raise seen on this fiber,
+      # which is the exception currently unwinding through the
+      # caller's frame. Stale otherwise; callers must gate on
+      # pop_and_raised_exit?, not read this unconditionally.
+      def current_exception_class_name
+        Thread.current[CLASS_KEY]
+      end
+
+      private
+
+      def counter
+        Thread.current[COUNTER_KEY] || 0
+      end
+
+      def on_raise(tp)
+        Thread.current[COUNTER_KEY] = counter + 1
+        Thread.current[CLASS_KEY] = exception_class_name(tp.raised_exception)
+      rescue Exception # rubocop:disable Lint/RescueException
+        nil
+      end
+
+      def on_rescue
+        Thread.current[COUNTER_KEY] = counter - 1
+      rescue Exception # rubocop:disable Lint/RescueException
+        nil
+      end
+
+      def exception_class_name(exception)
+        klass = exception.class
+        klass.respond_to?(:name) ? (klass.name || klass.to_s) : klass.to_s
+      rescue Exception # rubocop:disable Lint/RescueException
+        "Object"
+      end
+    end
+  end
+end

data/lib/bulldogger/probe/registry.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Bulldogger
+  module Probe
+    # Tracks which target labels currently have a live probe session,
+    # process-wide. Two concurrent sessions on the same method would
+    # each build their own TracePoint and double-count every call;
+    # the contract requires that be caught at start, by name, not
+    # discovered later as doubled statistics.
+    module Registry
+      @mutex = Mutex.new
+      @active = {}
+
+      class << self
+        def reserve!(labels)
+          @mutex.synchronize do
+            conflict = labels.find { |label| @active[label] }
+            if conflict
+              raise ArgumentError, "bulldogger: probe target #{conflict.inspect} is already being probed"
+            end
+
+            labels.each { |label| @active[label] = true }
+          end
+        end
+
+        def release(labels)
+          @mutex.synchronize { labels.each { |label| @active.delete(label) } }
+        end
+      end
+    end
+  end
+end