heapscope 0.6.0

data/lib/heapscope/report.rb

@@ -0,0 +1,308 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+
+module HeapScope
+  # Versioned report combining snapshots, diffs, findings, and presentation.
+  class Report
+    attr_reader :schema_version, :heapscope_version, :runtime_info, :summary,
+                :before, :after, :diff, :findings, :suspects, :classes,
+                :allocation_sites, :retention, :metadata, :limitations,
+                :budget_result, :thread_locals, :reproduction,
+                :fibers, :globals, :closures, :dominators, :fragmentation,
+                :aging, :gc_correlation, :retention_paths
+
+    def initialize(**attrs)
+      @schema_version = attrs[:schema_version] || SCHEMA_VERSION
+      @heapscope_version = attrs[:heapscope_version] || VERSION
+      @runtime_info = attrs[:runtime_info] || {}
+      @summary = attrs[:summary] || {}
+      @before = attrs[:before]
+      @after = attrs[:after]
+      @diff = attrs[:diff]
+      @findings = attrs[:findings] || []
+      @suspects = attrs[:suspects] || []
+      @classes = attrs[:classes] || []
+      @allocation_sites = attrs[:allocation_sites] || []
+      @retention = attrs[:retention]
+      @metadata = attrs[:metadata] || {}
+      @limitations = attrs[:limitations] || []
+      @budget_result = attrs[:budget_result]
+      @thread_locals = attrs[:thread_locals]
+      @reproduction = attrs[:reproduction]
+      @fibers = attrs[:fibers]
+      @globals = attrs[:globals]
+      @closures = attrs[:closures]
+      @dominators = attrs[:dominators]
+      @fragmentation = attrs[:fragmentation]
+      @aging = attrs[:aging]
+      @gc_correlation = attrs[:gc_correlation]
+      @retention_paths = attrs[:retention_paths]
+    end
+
+    def healthy?
+      summary[:healthy] == true || (findings.empty? && suspects.none? { |s| s[:severity] == :high })
+    end
+
+    def retained_count_for(klass)
+      name = klass.is_a?(Module) ? klass.name : klass.to_s
+      row = classes.find { |c| c[:name] == name || c["name"] == name }
+      return row[:delta_count] || row["delta_count"] if row
+
+      return 0 unless diff
+
+      delta = diff.class_deltas.find { |c| c[:name] == name }
+      delta ? delta[:delta_count] : 0
+    end
+
+    def retained_bytes_for(klass)
+      name = klass.is_a?(Module) ? klass.name : klass.to_s
+      return 0 unless diff
+
+      delta = diff.class_deltas.find { |c| c[:name] == name }
+      delta ? delta[:delta_bytes] : 0
+    end
+
+    def passed_budget?
+      budget_result.nil? || budget_result[:passed]
+    end
+
+    def print(io = $stdout)
+      io.puts to_text
+      self
+    end
+
+    def to_s
+      to_text
+    end
+
+    def to_text
+      Report::Text.render(self)
+    end
+
+    def to_markdown
+      Report::Markdown.render(self)
+    end
+
+    def save_markdown(path)
+      File.write(path, to_markdown)
+      path
+    end
+
+    def to_h
+      {
+        schema_version: schema_version,
+        heapscope_version: heapscope_version,
+        runtime: runtime_info,
+        summary: summary,
+        metadata: metadata,
+        limitations: limitations,
+        before: before&.to_h,
+        after: after&.to_h,
+        diff: diff_hash,
+        classes: classes,
+        allocation_sites: allocation_sites,
+        findings: findings.map { |f| f.respond_to?(:to_h) ? f.to_h : f },
+        suspects: suspects,
+        retention: retention,
+        budget_result: budget_result,
+        thread_locals: thread_locals,
+        reproduction: reproduction,
+        fibers: fibers,
+        globals: globals,
+        closures: closures,
+        dominators: dominators&.map { |d| d.respond_to?(:to_h) ? d.to_h : d },
+        fragmentation: fragmentation,
+        aging: aging,
+        gc_correlation: gc_correlation,
+        retention_paths: retention_paths
+      }.compact
+    end
+
+    def to_json(*_args)
+      JSON.pretty_generate(to_h)
+    end
+
+    def save(path)
+      File.write(path, to_json)
+      path
+    end
+
+    def scorecard(title: metadata[:title] || metadata["title"] || "HeapScope")
+      Scorecard.from_report(self, title: title)
+    end
+
+    def table(format: :ascii)
+      return "" unless diff
+
+      Tables.class_growth(diff, format: format)
+    end
+
+    def findings_table(format: :ascii)
+      Tables.findings(self, format: format)
+    end
+
+    def next_steps(limit: 8)
+      Suggest.next_steps(self, limit: limit)
+    end
+
+    def ranked_findings
+      Findings.rank_and_dedupe(findings)
+    end
+
+    def save_html(path)
+      File.write(path, Report::HTML.render(self))
+      path
+    end
+
+    def self.load(path)
+      data = JSON.parse(File.read(path), symbolize_names: true)
+      Schema.validate!(data)
+      from_h(data)
+    end
+
+    def self.from_h(data)
+      before = data[:before] ? Snapshot.from_h(data[:before]) : nil
+      after = data[:after] ? Snapshot.from_h(data[:after]) : nil
+      diff = before && after ? Diff.new(before, after) : nil
+      findings = Array(data[:findings]).map do |f|
+        Finding.new(
+          code: f[:code],
+          severity: f[:severity]&.to_sym,
+          title: f[:title],
+          facts: f[:facts],
+          derived: f[:derived],
+          hypothesis: f[:hypothesis],
+          suspected_cause: f[:suspected_cause],
+          evidence: f[:evidence],
+          suggestions: f[:suggestions],
+          subject: f[:subject]
+        )
+      end
+
+      new(
+        schema_version: data[:schema_version],
+        heapscope_version: data[:heapscope_version],
+        runtime_info: data[:runtime] || {},
+        summary: data[:summary] || {},
+        before: before,
+        after: after,
+        diff: diff,
+        findings: findings,
+        suspects: data[:suspects] || [],
+        classes: data[:classes] || diff&.class_deltas || [],
+        allocation_sites: data[:allocation_sites] || [],
+        retention: data[:retention],
+        metadata: data[:metadata] || {},
+        limitations: data[:limitations] || [],
+        budget_result: data[:budget_result],
+        thread_locals: data[:thread_locals],
+        reproduction: data[:reproduction],
+        fibers: data[:fibers],
+        globals: data[:globals],
+        closures: data[:closures],
+        dominators: data[:dominators],
+        fragmentation: data[:fragmentation],
+        aging: data[:aging],
+        gc_correlation: data[:gc_correlation],
+        retention_paths: data[:retention_paths]
+      )
+    end
+
+    def self.from_diff(diff, analysis:, metadata: {})
+      limitations = (diff.before.limitations + diff.after.limitations).uniq
+      frag = Fragmentation.assess(diff.after)
+      new(
+        runtime_info: {
+          ruby: RUBY_VERSION,
+          engine: RUBY_ENGINE,
+          platform: RUBY_PLATFORM
+        },
+        summary: analysis[:summary],
+        before: diff.before,
+        after: diff.after,
+        diff: diff,
+        findings: analysis[:findings],
+        suspects: analysis[:suspects],
+        classes: diff.class_deltas.sort_by { |c| -c[:delta_count].abs },
+        allocation_sites: diff.allocation_deltas.first(50),
+        fragmentation: frag,
+        reproduction: {
+          command: Reproduction.command(metadata),
+          captured_at: Time.now.utc.iso8601
+        },
+        metadata: metadata,
+        limitations: limitations
+      )
+    end
+
+    def self.from_retention_session(session)
+      analysis = Analyzer.new.analyze_retention(session)
+      first = session.samples.first&.snapshot
+      last = session.samples.last&.snapshot
+      diff = first && last ? Diff.new(first, last) : nil
+      diff_analysis = if diff
+                        Analyzer.new.analyze_diff(diff,
+                                                  context: { force_gc: session.force_gc })
+                      else
+                        { findings: [], suspects: [],
+                          summary: {} }
+                      end
+
+      extras = Analyzer.new.enrich_session(session, last)
+      all_findings = Findings.rank_and_dedupe(
+        analysis[:findings] + diff_analysis[:findings] + Array(extras[:findings])
+      )
+      new(
+        runtime_info: { ruby: RUBY_VERSION, engine: RUBY_ENGINE, platform: RUBY_PLATFORM },
+        summary: analysis[:summary].merge(diff_analysis[:summary] || {}).merge(
+          healthy: analysis[:persistent].empty? && all_findings.none? { |f| f.severity == :high }
+        ),
+        before: first,
+        after: last,
+        diff: diff,
+        findings: all_findings,
+        suspects: diff_analysis[:suspects],
+        classes: diff&.class_deltas || [],
+        retention: {
+          samples: session.samples.size,
+          force_gc: session.force_gc,
+          persistent: analysis[:persistent].first(20),
+          class_series: analysis[:class_series].values
+                                               .select { |e| e[:delta].abs > 0 }
+                                               .sort_by { |e| -e[:delta].abs }
+                                               .first(50),
+          collections: analysis[:collections]
+        },
+        thread_locals: analysis[:thread_locals],
+        fibers: extras[:fibers],
+        globals: extras[:globals],
+        closures: extras[:closures],
+        dominators: extras[:dominators],
+        fragmentation: extras[:fragmentation],
+        aging: extras[:aging],
+        gc_correlation: extras[:gc_correlation],
+        retention_paths: extras[:retention_paths],
+        reproduction: {
+          command: Reproduction.command(kind: "retention_test", cycles: session.samples.size),
+          captured_at: Time.now.utc.iso8601
+        },
+        metadata: { kind: "retention_session" },
+        limitations: [first, last].compact.flat_map(&:limitations).uniq + Array(extras[:limitations])
+      )
+    end
+
+    private
+
+    def diff_hash
+      return nil unless diff
+
+      diff.to_h
+    end
+  end
+end
+
+require_relative "report/text"
+require_relative "report/html"
+require_relative "report/markdown"

data/lib/heapscope/retention.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module HeapScope
+  # Multi-cycle retention analysis. Tracks populations that survive GC repeatedly.
+  class RetentionSession
+    Sample = Struct.new(:index, :snapshot, :after_gc, keyword_init: true)
+
+    attr_reader :samples, :config, :force_gc
+
+    def initialize(force_gc: true, mode: :lightweight, metadata: {})
+      @force_gc = force_gc
+      @mode = mode
+      @metadata = metadata
+      @samples = []
+      @config = HeapScope.config
+      @collector = Collector.new
+    end
+
+    def sample(label: nil)
+      GC.start if force_gc
+      snap = @collector.capture(
+        mode: @mode,
+        metadata: @metadata.merge(sample_index: @samples.size, label: label)
+      )
+      @samples << Sample.new(index: @samples.size, snapshot: snap, after_gc: force_gc)
+      snap
+    end
+
+    def finish
+      Report.from_retention_session(self)
+    end
+
+    def class_series
+      names = samples.flat_map { |s| s.snapshot.class_stats.keys }.uniq
+      names.each_with_object({}) do |name, hash|
+        series = samples.map { |s| s.snapshot.class_count(name) }
+        hash[name] = {
+          name: name,
+          series: series,
+          trend: Growth.analyze(series),
+          delta: series.last.to_i - series.first.to_i
+        }
+      end
+    end
+
+    def persistent_classes(min_cycles: 3, min_delta: 10)
+      class_series.values.select do |entry|
+        trend = entry[:trend]
+        next false if entry[:series].size < min_cycles
+        next false if entry[:delta] < min_delta
+        next false if config.ignore_class?(entry[:name])
+
+        %i[monotonic_growth linear_growth exponential_like].include?(trend[:pattern])
+      end.sort_by { |e| -e[:delta] }
+    end
+  end
+
+  # Allocation tracing helpers — opt-in only; never globally enable by surprise.
+  class AllocationTracer
+    def initialize(runtime: Runtime.current)
+      @runtime = runtime
+      @active = false
+    end
+
+    def available?
+      @runtime.allocation_tracing?
+    end
+
+    def start!
+      return false unless available?
+
+      @runtime.start_allocation_tracing
+      @active = true
+      true
+    end
+
+    def stop!
+      return unless @active
+
+      @runtime.stop_allocation_tracing
+      @active = false
+    end
+
+    def with_tracing
+      started = start!
+      yield
+    ensure
+      stop! if started
+    end
+  end
+end

data/lib/heapscope/rspec.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require "heapscope"
+
+# Optional RSpec matchers: require "heapscope/rspec"
+module HeapScope
+  module RSpecMatchers
+    class RetainLessThan
+      def initialize(limit)
+        @limit = limit
+        @unit = :objects
+        @klass = nil
+        @report = nil
+      end
+
+      def objects
+        @unit = :objects
+        self
+      end
+
+      def bytes
+        @unit = :bytes
+        self
+      end
+
+      def of(klass)
+        @klass = klass
+        self
+      end
+
+      def matches?(proc)
+        @report = HeapScope.measure(force_gc: true) { proc.call }
+        @actual =
+          if @klass
+            @unit == :bytes ? @report.retained_bytes_for(@klass) : @report.retained_count_for(@klass)
+          elsif @unit == :bytes
+            @report.diff&.heap_bytes_estimate_delta.to_i
+          else
+            @report.diff&.surviving_estimate.to_i
+          end
+        @actual < @limit
+      end
+
+      def failure_message
+        suspects = Array(@report&.suspects).first(5).map { |s| "#{s[:name]}(+#{s[:delta_count]})" }.join(", ")
+        "expected retained #{@unit}#{@klass ? " of #{@klass}" : ""} < #{@limit}, got #{@actual}. Suspects: #{suspects}"
+      end
+
+      def failure_message_when_negated
+        "expected retained #{@unit} >= #{@limit}, got #{@actual}"
+      end
+
+      def supports_block_expectations?
+        true
+      end
+    end
+
+    class GrowHeapByMoreThan
+      def initialize(bytes)
+        @bytes = bytes
+        @report = nil
+      end
+
+      def matches?(proc)
+        @report = HeapScope.measure(force_gc: true) { proc.call }
+        @actual = @report.diff&.heap_bytes_estimate_delta.to_i
+        @actual > @bytes
+      end
+
+      def failure_message
+        "expected heap growth > #{@bytes}, got #{@actual}"
+      end
+
+      def failure_message_when_negated
+        suspects = Array(@report&.suspects).first(5).map { |s| "#{s[:name]}(+#{s[:delta_count]})" }.join(", ")
+        "expected heap not to grow by more than #{@bytes}, got #{@actual}. Suspects: #{suspects}"
+      end
+
+      def supports_block_expectations?
+        true
+      end
+    end
+
+    class RemainHealthy
+      def matches?(proc)
+        @report = HeapScope.measure(force_gc: true) { proc.call }
+        @report.healthy? && @report.findings.none? { |f| f.severity == :high }
+      end
+
+      def failure_message
+        codes = @report.findings.map { |f| "#{f.code}/#{f.severity}" }.join(", ")
+        "expected healthy retention profile, findings: #{codes}"
+      end
+
+      def supports_block_expectations?
+        true
+      end
+    end
+
+    def retain_less_than(limit)
+      RetainLessThan.new(limit)
+    end
+
+    def grow_heap_by_more_than(bytes)
+      GrowHeapByMoreThan.new(bytes)
+    end
+
+    def heapscope_remain_healthy
+      RemainHealthy.new
+    end
+  end
+end
+
+if defined?(RSpec)
+  RSpec.configure do |config|
+    config.include HeapScope::RSpecMatchers
+  end
+end

data/lib/heapscope/runtime/base.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module HeapScope
+  module Runtime
+    # Shared runtime adapter interface. Implementations degrade safely.
+    class Base
+      attr_reader :engine
+
+      def initialize(engine: RUBY_ENGINE)
+        @engine = engine
+      end
+
+      def allocation_tracing?
+        false
+      end
+
+      def reachable_objects?
+        false
+      end
+
+      def memsize?
+        false
+      end
+
+      def rss_tracking?
+        rss_bytes
+        true
+      rescue StandardError
+        false
+      end
+
+      def each_object?
+        false
+      end
+
+      def gc_stat?
+        defined?(GC) && GC.respond_to?(:stat)
+      end
+
+      def gc_stat
+        return {} unless gc_stat?
+
+        normalize_gc_stat(GC.stat)
+      end
+
+      def rss_bytes
+        read_rss_bytes
+      end
+
+      def each_object(_klass = nil)
+        raise CapabilityError, "ObjectSpace.each_object is unavailable on #{engine}"
+      end
+
+      def memsize_of(_object)
+        nil
+      end
+
+      def reachable_objects_from(_object)
+        []
+      end
+
+      def start_allocation_tracing
+        raise CapabilityError, "Allocation tracing unavailable on #{engine}"
+      end
+
+      def stop_allocation_tracing
+        nil
+      end
+
+      def allocation_info(_object)
+        nil
+      end
+
+      def process_metadata
+        {
+          pid: Process.pid,
+          ppid: Process.ppid,
+          engine: engine,
+          ruby: RUBY_VERSION,
+          platform: RUBY_PLATFORM,
+          thread: Thread.current.name || Thread.current.object_id.to_s
+        }
+      end
+
+      private
+
+      INTERESTING_GC_KEYS = %i[
+        count time major_gc_count minor_gc_count
+        heap_live_slots heap_free_slots heap_available_slots heap_allocatable_slots
+        heap_allocated_pages heap_eden_pages heap_tomb_pages heap_sorted_length
+        total_allocated_objects total_freed_objects
+        malloc_increase_bytes malloc_increase_bytes_limit
+        old_objects oldmalloc_increase_bytes remembered_wb_unprotected_objects
+      ].freeze
+
+      def normalize_gc_stat(raw)
+        INTERESTING_GC_KEYS.each_with_object({}) do |key, hash|
+          hash[key] = raw[key] if raw.key?(key)
+        end
+      end
+
+      def read_rss_bytes
+        if File.readable?("/proc/self/status")
+          line = File.foreach("/proc/self/status").find { |l| l.start_with?("VmRSS:") }
+          return line.split[1].to_i * 1024 if line
+        end
+
+        macos_rss || windows_rss
+      end
+
+      def macos_rss
+        return nil unless RUBY_PLATFORM.include?("darwin")
+
+        out = `ps -o rss= -p #{Process.pid} 2>/dev/null`.to_s.strip
+        return nil if out.empty?
+
+        out.to_i * 1024
+      end
+
+      def windows_rss
+        return nil unless RUBY_PLATFORM.match?(/mswin|mingw|cygwin/i)
+
+        require_relative "windows_rss"
+        WindowsRSS.working_set_bytes
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/heapscope/runtime/jruby.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module HeapScope
+  module Runtime
+    # Placeholder adapter — JRuby introspection differs from MRI.
+    class JRuby < Base
+      def initialize
+        super(engine: "jruby")
+      end
+
+      def each_object?
+        defined?(ObjectSpace) && ObjectSpace.respond_to?(:each_object)
+      end
+
+      def each_object(klass = nil, &)
+        raise CapabilityError, "ObjectSpace.each_object unavailable on JRuby" unless each_object?
+
+        if klass
+          ObjectSpace.each_object(klass, &)
+        else
+          ObjectSpace.each_object(&)
+        end
+      end
+    end
+  end
+end