heapscope 0.6.0

data/lib/heapscope/dominators.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module HeapScope
+  # Approximate dominator-style analysis via bounded retained-size estimates.
+  # Explicitly labeled approximate — not a JVM-style precise dominator tree.
+  class Dominators
+    Candidate = Struct.new(:class_name, :shallow, :approx_retained, :objects, :note, keyword_init: true)
+
+    def initialize(runtime: Runtime.current, config: HeapScope.config)
+      @runtime = runtime
+      @config = config
+      @graph = Graph.new(runtime: runtime, config: config)
+    end
+
+    def top_retainers(sample_objects, limit: 10)
+      sample_objects.filter_map do |obj|
+        next if obj.nil?
+
+        est = @graph.estimate_retained_size(obj, max_objects: 2_000, max_depth: @config.max_graph_depth)
+        Candidate.new(
+          class_name: begin
+            obj.class.name
+          rescue StandardError
+            "unknown"
+          end,
+          shallow: est[:shallow],
+          approx_retained: est[:retained],
+          objects: est[:objects],
+          note: "Approximate retained size via bounded traversal — not a precise dominator."
+        )
+      rescue StandardError
+        nil
+      end.sort_by { |c| -(c.approx_retained || 0) }.first(limit)
+    end
+
+    def from_thread_locals(limit: 5)
+      roots = []
+      Thread.list.each do |thread|
+        next unless thread.respond_to?(:keys)
+
+        thread.each_key do |key|
+          roots << thread[key]
+        rescue StandardError
+          next
+        end
+      end
+      top_retainers(roots.compact.first(20), limit: limit)
+    end
+  end
+
+  # Heuristic fragmentation / native mismatch indicators.
+  module Fragmentation
+    module_function
+
+    def assess(snapshot)
+      gc = snapshot.gc_stat
+      rss = snapshot.rss_bytes
+      live = gc[:heap_live_slots]
+      free = gc[:heap_free_slots]
+      pages = gc[:heap_allocated_pages]
+      return { status: :unknown, note: "Insufficient GC/RSS data." } if rss.nil? || live.nil?
+
+      heap_bytes_estimate = live.to_i * 40 # very rough average slot estimate
+      ratio = heap_bytes_estimate.positive? ? rss.to_f / heap_bytes_estimate : nil
+      free_ratio = (live.to_i + free.to_i).positive? ? free.to_f / (live + free) : nil
+
+      status =
+        if ratio && ratio > 4.0 && pages.to_i > 100
+          :potential_fragmentation
+        elsif ratio && ratio > 2.5
+          :elevated_rss_vs_heap
+        else
+          :normal
+        end
+
+      {
+        status: status,
+        rss_bytes: rss,
+        heap_bytes_estimate: heap_bytes_estimate,
+        rss_to_heap_ratio: ratio&.round(2),
+        free_slot_ratio: free_ratio&.round(3),
+        heap_allocated_pages: pages,
+        note: "Potential allocator/heap fragmentation indicator — not confirmed fragmentation."
+      }
+    end
+  end
+end

data/lib/heapscope/errors.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module HeapScope
+  class Error < StandardError; end
+
+  class UnsupportedRuntimeError < Error; end
+  class SnapshotError < Error; end
+  class InvalidReportError < Error; end
+  class CapabilityError < Error; end
+  class AnalysisLimitError < Error; end
+  class ConfigurationError < Error; end
+  class BudgetExceededError < Error; end
+end

data/lib/heapscope/extrapolation.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module HeapScope
+  # Extrapolates retention rate into a labeled estimate. Never presented as guaranteed.
+  module Extrapolation
+    module_function
+
+    def retention_per_hour(retained_bytes:, elapsed_seconds:)
+      return nil if elapsed_seconds.nil? || elapsed_seconds <= 0 || retained_bytes.nil?
+
+      rate = retained_bytes.to_f / elapsed_seconds
+      {
+        bytes_per_second: rate.round(2),
+        bytes_per_hour: (rate * 3600).round,
+        label: "extrapolation",
+        caveat: "At the current observed retention rate — not a prediction of future usage."
+      }
+    end
+
+    def objects_per_run(retained_objects:, runs:)
+      return nil if runs.nil? || runs <= 0
+
+      {
+        retained_objects_per_run: (retained_objects.to_f / runs).round(2),
+        label: "per-run retention"
+      }
+    end
+  end
+
+  # Classifies churn vs sticky populations for reports.
+  module Classification
+    module_function
+
+    def churn_vs_leak(allocated:, retained:)
+      allocated = allocated.to_i
+      retained = retained.to_i
+      return :insufficient_data if allocated <= 0
+
+      ratio = retained.to_f / allocated
+      if allocated > 10_000 && ratio < 0.05
+        :high_churn_low_retention
+      elsif allocated < 1_000 && ratio > 0.5
+        :sticky
+      elsif allocated > 10_000 && ratio > 0.3
+        :severe
+      else
+        :normal
+      end
+    end
+  end
+end

data/lib/heapscope/findings.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module HeapScope
+  # Stable diagnostic codes. Each finding separates facts, derived behavior,
+  # hypothesis, and suspected cause — never collapsed into fake certainty.
+  module Diagnostics
+    CODES = {
+      "HS001" => {
+        id: "HS001",
+        name: "persistent_class_growth",
+        title: "Persistent object population growth",
+        default_severity: :medium
+      },
+      "HS002" => {
+        id: "HS002",
+        name: "high_retention_ratio",
+        title: "High retention ratio after workload",
+        default_severity: :high
+      },
+      "HS003" => {
+        id: "HS003",
+        name: "thread_local_retention",
+        title: "Thread-local retention pattern",
+        default_severity: :high
+      },
+      "HS004" => {
+        id: "HS004",
+        name: "unbounded_collection",
+        title: "Unbounded collection growth candidate",
+        default_severity: :high
+      },
+      "HS005" => {
+        id: "HS005",
+        name: "callback_accumulation",
+        title: "Callback or subscriber accumulation",
+        default_severity: :medium
+      },
+      "HS006" => {
+        id: "HS006",
+        name: "closure_retention",
+        title: "Proc/closure retention candidate",
+        default_severity: :medium
+      },
+      "HS007" => {
+        id: "HS007",
+        name: "poor_gc_recovery",
+        title: "Poor recovery after forced GC",
+        default_severity: :medium
+      },
+      "HS008" => {
+        id: "HS008",
+        name: "baseline_regression",
+        title: "Memory retention regression vs baseline",
+        default_severity: :high
+      },
+      "HS009" => {
+        id: "HS009",
+        name: "high_allocation_pressure",
+        title: "High allocation pressure (churn)",
+        default_severity: :low
+      },
+      "HS010" => {
+        id: "HS010",
+        name: "native_memory_mismatch",
+        title: "RSS growth without matching Ruby heap growth",
+        default_severity: :medium
+      }
+    }.freeze
+  end
+
+  # Ranking / dedupe helpers for findings lists.
+  module Findings
+    SEVERITY_WEIGHT = { high: 100, medium: 50, low: 10 }.freeze
+    CODE_PRIORITY = {
+      "HS002" => 20,
+      "HS003" => 18,
+      "HS004" => 18,
+      "HS008" => 17,
+      "HS001" => 15,
+      "HS007" => 14,
+      "HS005" => 12,
+      "HS006" => 12,
+      "HS010" => 10,
+      "HS009" => 4
+    }.freeze
+
+    module_function
+
+    def priority_score(finding)
+      sev = SEVERITY_WEIGHT[finding.severity] || 0
+      code = CODE_PRIORITY[finding.code] || 1
+      sev + code
+    end
+
+    def rank_and_dedupe(findings)
+      grouped = Array(findings).group_by { |f| [f.code, f.subject.to_s] }
+      deduped = grouped.map do |_key, list|
+        list.max_by { |f| priority_score(f) }
+      end
+      deduped.sort_by { |f| [-priority_score(f), f.code.to_s, f.subject.to_s] }
+    end
+  end
+
+  class Finding
+    attr_reader :code, :severity, :title, :facts, :derived, :hypothesis,
+                :suspected_cause, :evidence, :suggestions, :subject
+
+    def initialize(code:, severity:, title: nil, facts: [], derived: [],
+                   hypothesis: nil, suspected_cause: nil, evidence: [],
+                   suggestions: [], subject: nil)
+      meta = Diagnostics::CODES[code] || {}
+      @code = code
+      @severity = severity || meta[:default_severity] || :low
+      @title = title || meta[:title] || code
+      @facts = Array(facts)
+      @derived = Array(derived)
+      @hypothesis = hypothesis
+      @suspected_cause = suspected_cause
+      @evidence = Array(evidence)
+      @suggestions = Array(suggestions)
+      @subject = subject
+    end
+
+    def name
+      Diagnostics::CODES.dig(code, :name)
+    end
+
+    def priority
+      Findings.priority_score(self)
+    end
+
+    def to_h
+      {
+        code: code,
+        name: name,
+        severity: severity.to_s,
+        title: title,
+        subject: subject,
+        priority: priority,
+        facts: facts,
+        derived: derived,
+        hypothesis: hypothesis,
+        suspected_cause: suspected_cause,
+        evidence: evidence,
+        suggestions: suggestions
+      }.compact
+    end
+  end
+end

data/lib/heapscope/globals.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require "set"
+
+module HeapScope
+  # Global / constant / class-variable retention candidates.
+  module Globals
+    module_function
+
+    def inventory(max_entries: 200)
+      items = []
+      items.concat(global_variables_inventory)
+      items.concat(constant_registry_hints)
+      items.first(max_entries)
+    rescue StandardError => e
+      [{ error: e.message }]
+    end
+
+    def global_variables_inventory
+      global_variables.map do |name|
+        next if name == :$= # deprecated / noisy
+
+        value = begin
+          eval(name.to_s) # rubocop:disable Security/Eval -- inspecting known global variable names only
+        rescue StandardError
+          nil
+        end
+        next if value.nil?
+
+        {
+          kind: :global_variable,
+          name: name.to_s,
+          class: value.class.name,
+          size_hint: size_hint(value),
+          shallow_bytes: Runtime.current.memsize_of(value)
+        }
+      end.compact
+    end
+
+    def constant_registry_hints
+      suspects = []
+      Object.constants.each do |const_name|
+        const = begin
+          Object.const_get(const_name)
+        rescue StandardError
+          next
+        end
+        next unless const.is_a?(Module)
+
+        %i[REGISTRY CACHE STORE HANDLERS LISTENERS SUBSCRIBERS].each do |hint|
+          next unless const.const_defined?(hint, false)
+
+          value = const.const_get(hint)
+          suspects << {
+            kind: :constant,
+            name: "#{const.name}::#{hint}",
+            class: value.class.name,
+            size_hint: size_hint(value),
+            shallow_bytes: Runtime.current.memsize_of(value)
+          }
+        end
+      rescue StandardError
+        next
+      end
+      suspects
+    end
+
+    def growing_findings(previous:, current:)
+      findings = []
+      prev_map = previous.to_h { |i| [i[:name], i] }
+      current.each do |item|
+        before = prev_map[item[:name]]
+        next unless before
+
+        before_size = before[:size_hint].to_i
+        after_size = item[:size_hint].to_i
+        next unless after_size > before_size + 50
+
+        findings << Finding.new(
+          code: "HS004",
+          severity: after_size > before_size * 2 ? :high : :medium,
+          subject: item[:name],
+          facts: [
+            "Observed fact: #{item[:name]} size hint #{before_size} → #{after_size}."
+          ],
+          derived: ["Derived: global/constant collection grew between samples."],
+          hypothesis: "A module-level registry or global collection may be accumulating entries.",
+          suspected_cause: item[:name],
+          suggestions: [
+            "Bound or clear #{item[:name]}",
+            "Confirm intentional caching vs accidental append"
+          ],
+          evidence: [{ before: before, after: item }]
+        )
+      end
+      findings
+    end
+
+    def size_hint(value)
+      case value
+      when Array, Hash, Set then value.size
+      else 1
+      end
+    rescue StandardError
+      0
+    end
+  end
+end

data/lib/heapscope/graph.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+module HeapScope
+  # Bounded reachability / retention-path analysis for deep mode.
+  # Never fabricates roots; reports nearest observed retainer when uncertain.
+  class Graph
+    Node = Struct.new(:local_id, :class_name, :ruby_object_id, :label, keyword_init: true)
+    Edge = Struct.new(:from, :to, :via, keyword_init: true)
+    Path = Struct.new(:nodes, :confidence, :note, keyword_init: true)
+
+    def initialize(runtime: Runtime.current, config: HeapScope.config)
+      @runtime = runtime
+      @config = config
+    end
+
+    def available?
+      @runtime.reachable_objects?
+    end
+
+    # BFS for a short human-understandable retention path from known roots.
+    def retention_path(target, roots: nil, max_depth: nil, max_edges: nil)
+      max_depth ||= @config.max_graph_depth
+      max_edges ||= @config.max_edges
+      return unavailable_path("reachable_objects API unavailable") unless available?
+
+      roots ||= default_roots
+      visited = {}
+      parent = {}
+      via = {}
+      queue = []
+      edges = 0
+      target_id = target.__id__
+
+      roots.each do |root, label|
+        id = root.__id__
+        next if visited[id]
+
+        visited[id] = true
+        queue << root
+        parent[id] = nil
+        via[id] = label
+      end
+
+      found = nil
+      while (current = queue.shift)
+        break if edges >= max_edges
+
+        depth = depth_of(current.__id__, parent)
+        next if depth >= max_depth
+
+        children = safe_reachable(current)
+        children.each_with_index do |child, idx|
+          edges += 1
+          break if edges >= max_edges
+
+          cid = child.__id__
+          next if visited[cid]
+
+          visited[cid] = true
+          parent[cid] = current.__id__
+          via[cid] = edge_label(current, child, idx)
+          queue << child
+          if cid == target_id
+            found = child
+            break
+          end
+        end
+        break if found
+      end
+
+      if found
+        build_path(found, parent, via, :high, "Bounded BFS path from known roots")
+      else
+        nearest = nearest_retainer(target)
+        Path.new(
+          nodes: nearest,
+          confidence: :low,
+          note: "Nearest observed retainer; true root not identified within budget"
+        )
+      end
+    rescue AnalysisLimitError => e
+      Path.new(nodes: [], confidence: :low, note: e.message)
+    end
+
+    def estimate_retained_size(root, max_objects: nil, max_depth: nil)
+      max_objects ||= [@config.max_objects, 10_000].min
+      max_depth ||= @config.max_graph_depth
+      return { shallow: @runtime.memsize_of(root), retained: nil, note: "unavailable" } unless available?
+
+      seen = {}
+      total = 0
+      count = 0
+      queue = [[root, 0]]
+      seen[root.__id__] = true
+
+      while (pair = queue.shift)
+        obj, depth = pair
+        count += 1
+        break if count >= max_objects
+
+        total += @runtime.memsize_of(obj).to_i
+        next if depth >= max_depth
+
+        safe_reachable(obj).each do |child|
+          cid = child.__id__
+          next if seen[cid]
+
+          seen[cid] = true
+          queue << [child, depth + 1]
+        end
+      end
+
+      {
+        shallow: @runtime.memsize_of(root),
+        retained: total,
+        objects: count,
+        approximate: true,
+        note: "Approximate retained size via bounded traversal"
+      }
+    end
+
+    def thread_local_inventory
+      Thread.list.map do |thread|
+        keys =
+          if thread.respond_to?(:keys)
+            thread.keys
+          else
+            []
+          end
+        values = keys.each_with_object({}) do |key, hash|
+          value = thread[key]
+          hash[key.inspect] = {
+            class: value.class.name,
+            shallow_bytes: @runtime.memsize_of(value)
+          }
+        rescue StandardError
+          hash[key.inspect] = { class: "unknown" }
+        end
+
+        {
+          name: thread.name || "thread-#{thread.object_id}",
+          status: thread.status,
+          keys: values
+        }
+      end
+    end
+
+    def unbounded_collection_candidates(_samples)
+      # samples: array of { object_local_id/class/size } or class series sizes for Array/Hash
+      []
+    end
+
+    private
+
+    def default_roots
+      roots = []
+      roots << [Object, "constant:Object"]
+      begin
+        Thread.list.each { |t| roots << [t, "thread:#{t.name || t.object_id}"] }
+      rescue StandardError
+        nil
+      end
+      roots << [Fiber.current, "fiber:current"] if defined?(Fiber) && Fiber.respond_to?(:current)
+      roots
+    end
+
+    def safe_reachable(object)
+      @runtime.reachable_objects_from(object).grep(Object)
+    rescue StandardError
+      []
+    end
+
+    def edge_label(parent, _child, index)
+      case parent
+      when Hash then "hash_entry"
+      when Array then "array[#{index}]"
+      when Thread then "thread_reference"
+      else "ivars/refs"
+      end
+    end
+
+    def depth_of(id, parent)
+      d = 0
+      cur = id
+      while parent[cur]
+        d += 1
+        cur = parent[cur]
+        break if d > 10_000
+      end
+      d
+    end
+
+    def build_path(target, parent, via, confidence, note)
+      cur = target.__id__
+      chain = []
+      while cur
+        chain << cur
+        cur = parent[cur]
+      end
+      nodes = chain.reverse.map do |id|
+        { object_id: id, via: via[id] }
+      end
+      Path.new(nodes: nodes, confidence: confidence, note: note)
+    end
+
+    def nearest_retainer(target)
+      refs = safe_reachable(target)
+      [{ class: target.class.name, note: "target" }] +
+        refs.first(5).map { |o| { class: o.class.name, note: "reachable_neighbor" } }
+    rescue StandardError
+      [{ class: target.class.name, note: "target_only" }]
+    end
+
+    def unavailable_path(note)
+      Path.new(nodes: [], confidence: :low, note: note)
+    end
+  end
+end