heapscope 0.6.0

data/lib/heapscope/runtime/mri.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "objspace"
+require_relative "base"
+
+module HeapScope
+  module Runtime
+    class MRI < Base
+      def initialize
+        super(engine: "ruby")
+      end
+
+      def allocation_tracing?
+        ObjectSpace.respond_to?(:trace_object_allocations_start)
+      end
+
+      def reachable_objects?
+        ObjectSpace.respond_to?(:reachable_objects_from)
+      end
+
+      def memsize?
+        ObjectSpace.respond_to?(:memsize_of)
+      end
+
+      def each_object?
+        ObjectSpace.respond_to?(:each_object)
+      end
+
+      def each_object(klass = nil, &)
+        raise CapabilityError, "ObjectSpace.each_object unavailable" unless each_object?
+
+        if klass
+          ObjectSpace.each_object(klass, &)
+        else
+          ObjectSpace.each_object(&)
+        end
+      end
+
+      def memsize_of(object)
+        return nil unless memsize?
+
+        ObjectSpace.memsize_of(object)
+      rescue StandardError
+        nil
+      end
+
+      def reachable_objects_from(object)
+        return [] unless reachable_objects?
+
+        ObjectSpace.reachable_objects_from(object) || []
+      rescue StandardError
+        []
+      end
+
+      def start_allocation_tracing
+        raise CapabilityError, "Allocation tracing unavailable" unless allocation_tracing?
+
+        ObjectSpace.trace_object_allocations_start
+      end
+
+      def stop_allocation_tracing
+        return unless allocation_tracing?
+
+        ObjectSpace.trace_object_allocations_stop
+      end
+
+      def allocation_info(object)
+        return nil unless allocation_tracing?
+
+        file = ObjectSpace.allocation_sourcefile(object)
+        line = ObjectSpace.allocation_sourceline(object)
+        return nil unless file
+
+        {
+          file: file,
+          line: line,
+          generation: (ObjectSpace.allocation_generation(object) if ObjectSpace.respond_to?(:allocation_generation)),
+          class_path: (ObjectSpace.allocation_class_path(object) if ObjectSpace.respond_to?(:allocation_class_path)),
+          method_id: (ObjectSpace.allocation_method_id(object) if ObjectSpace.respond_to?(:allocation_method_id))
+        }.compact
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/heapscope/runtime/truffleruby.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module HeapScope
+  module Runtime
+    # Placeholder adapter — TruffleRuby support may expand later.
+    class TruffleRuby < Base
+      def initialize
+        super(engine: "truffleruby")
+      end
+
+      def each_object?
+        defined?(ObjectSpace) && ObjectSpace.respond_to?(:each_object)
+      end
+
+      def memsize?
+        defined?(ObjectSpace) && ObjectSpace.respond_to?(:memsize_of)
+      end
+
+      def each_object(klass = nil, &)
+        raise CapabilityError, "ObjectSpace.each_object unavailable on TruffleRuby" unless each_object?
+
+        if klass
+          ObjectSpace.each_object(klass, &)
+        else
+          ObjectSpace.each_object(&)
+        end
+      end
+
+      def memsize_of(object)
+        return nil unless memsize?
+
+        ObjectSpace.memsize_of(object)
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/heapscope/runtime/windows_rss.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module HeapScope
+  module Runtime
+    # Windows working-set size via PowerShell (no native gem required).
+    # Optionally uses stdlib Fiddle when already loaded / available without warnings noise.
+    module WindowsRSS
+      module_function
+
+      def working_set_bytes
+        powershell_working_set_bytes || fiddle_working_set_bytes
+      end
+
+      def powershell_working_set_bytes
+        out = `powershell -NoProfile -Command "(Get-Process -Id #{Process.pid}).WorkingSet64"`.to_s.strip
+        return nil if out.empty?
+
+        Integer(out)
+      rescue StandardError
+        nil
+      end
+
+      def fiddle_working_set_bytes
+        return nil unless Object.const_defined?(:Fiddle)
+
+        require "fiddle/import"
+        api.working_set_bytes
+      rescue StandardError
+        nil
+      end
+
+      def api
+        @api ||= build_api
+      end
+
+      def build_api
+        Module.new do
+          extend Fiddle::Importer
+
+          dlload "kernel32.dll", "psapi.dll"
+          typealias "DWORD", "unsigned long"
+          typealias "HANDLE", "void*"
+          typealias "SIZE_T", "size_t"
+          typealias "BOOL", "int"
+
+          const_set(
+            :Counters,
+            struct([
+                     "DWORD cb",
+                     "DWORD PageFaultCount",
+                     "SIZE_T PeakWorkingSetSize",
+                     "SIZE_T WorkingSetSize",
+                     "SIZE_T QuotaPeakPagedPoolUsage",
+                     "SIZE_T QuotaPagedPoolUsage",
+                     "SIZE_T QuotaPeakNonPagedPoolUsage",
+                     "SIZE_T QuotaNonPagedPoolUsage",
+                     "SIZE_T PagefileUsage",
+                     "SIZE_T PeakPagefileUsage"
+                   ])
+          )
+
+          extern "HANDLE GetCurrentProcess()"
+          extern "BOOL GetProcessMemoryInfo(HANDLE, void*, DWORD)"
+
+          define_singleton_method(:working_set_bytes) do
+            counters = const_get(:Counters).malloc
+            counters.cb = const_get(:Counters).size
+            ok = GetProcessMemoryInfo(GetCurrentProcess(), counters, counters.cb)
+            ok.zero? ? nil : counters.WorkingSetSize
+          end
+        end
+      end
+    end
+  end
+end

data/lib/heapscope/runtime.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "runtime/base"
+require_relative "runtime/mri"
+require_relative "runtime/jruby"
+require_relative "runtime/truffleruby"
+
+module HeapScope
+  module Runtime
+    module_function
+
+    def current
+      @current ||= detect
+    end
+
+    def reset!
+      @current = nil
+    end
+
+    def detect
+      case RUBY_ENGINE
+      when "ruby"
+        MRI.new
+      when "jruby"
+        JRuby.new
+      when "truffleruby"
+        TruffleRuby.new
+      else
+        Base.new(engine: RUBY_ENGINE)
+      end
+    end
+  end
+end

data/lib/heapscope/schema.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module HeapScope
+  # Validates versioned report JSON payloads.
+  module Schema
+    REQUIRED_ROOT = %i[schema_version heapscope_version].freeze
+
+    module_function
+
+    def validate!(data)
+      data = data.transform_keys(&:to_sym) if data.respond_to?(:transform_keys)
+      missing = REQUIRED_ROOT.reject { |k| data.key?(k) }
+      raise InvalidReportError, "Missing keys: #{missing.join(', ')}" unless missing.empty?
+
+      version = data[:schema_version].to_i
+      raise InvalidReportError, "Unsupported schema_version=#{version}" if version < 1 || version > SCHEMA_VERSION
+
+      true
+    end
+
+    def valid?(data)
+      validate!(data)
+      true
+    rescue InvalidReportError
+      false
+    end
+  end
+end

data/lib/heapscope/scorecard.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module HeapScope
+  # One-shot probe that prints an executive scorecard for a workload.
+  class Probe
+    Result = Struct.new(:report, :scorecard, :printed, keyword_init: true)
+
+    def self.run(title: "probe", force_gc: true, mode: :lightweight, print: true, &block)
+      new(title: title, force_gc: force_gc, mode: mode, print: print).run(&block)
+    end
+
+    def initialize(title:, force_gc:, mode:, print:)
+      @title = title
+      @force_gc = force_gc
+      @mode = mode
+      @print = print
+    end
+
+    def run(&)
+      raise ArgumentError, "block required" unless block_given?
+
+      report = HeapScope.measure(force_gc: @force_gc, mode: @mode, metadata: { kind: "probe", title: @title }, &)
+      scorecard = Scorecard.from_report(report, title: @title)
+      puts scorecard.to_text if @print && !HeapScope.config.quiet
+      Result.new(report: report, scorecard: scorecard, printed: @print)
+    end
+  end
+
+  # Compact executive summary for CI logs and consoles.
+  class Scorecard
+    attr_reader :title, :verdict, :rss_delta, :live_delta, :retention_ratio,
+                :top_suspects, :finding_codes, :healthy
+
+    def self.from_report(report, title: "HeapScope")
+      new(
+        title: title,
+        healthy: report.healthy?,
+        verdict: report.healthy? ? "HEALTHY" : "ATTENTION",
+        rss_delta: report.diff&.rss_delta,
+        live_delta: report.diff&.heap_live_delta,
+        retention_ratio: report.diff&.retention_ratio,
+        top_suspects: Array(report.suspects).first(3).map { |s| "#{s[:name]}(+#{s[:delta_count]}/#{s[:severity]})" },
+        finding_codes: report.findings.map { |f| "#{f.code}:#{f.severity}" }
+      )
+    end
+
+    def initialize(**attrs)
+      attrs.each { |k, v| instance_variable_set("@#{k}", v) }
+    end
+
+    def to_h
+      {
+        title: title,
+        verdict: verdict,
+        healthy: healthy,
+        rss_delta: rss_delta,
+        live_delta: live_delta,
+        retention_ratio: retention_ratio,
+        top_suspects: top_suspects,
+        finding_codes: finding_codes
+      }
+    end
+
+    def to_text
+      lines = []
+      lines << "┌─ HeapScope scorecard ─────────────────────────"
+      lines << "│ #{title}"
+      lines << "│ Verdict: #{verdict}"
+      lines << "│ RSS Δ: #{fmt_bytes(rss_delta)}   Live slots Δ: #{live_delta || 'n/a'}"
+      lines << "│ Retention: #{retention_ratio ? format('%.2f%%', retention_ratio * 100) : 'n/a'}"
+      lines << "│ Suspects: #{top_suspects.empty? ? 'none' : top_suspects.join(', ')}"
+      lines << "│ Findings: #{finding_codes.empty? ? 'none' : finding_codes.join(', ')}"
+      lines << "└───────────────────────────────────────────────"
+      lines.join("\n")
+    end
+
+    private
+
+    def fmt_bytes(n)
+      return "n/a" if n.nil?
+
+      format("%+.2f MB", n.to_f / (1024 * 1024))
+    end
+  end
+end

data/lib/heapscope/session.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "securerandom"
+require "time"
+
+module HeapScope
+  # Named diagnostic sessions that persist artifacts under `.heapscope/`.
+  class Session
+    attr_reader :name, :dir, :id, :created_at, :reports
+
+    def self.open(name, root: Dir.pwd)
+      new(name, root: root).tap(&:ensure!)
+    end
+
+    def initialize(name, root: Dir.pwd)
+      @name = name.to_s
+      @id = SecureRandom.hex(4)
+      @root = root
+      @dir = File.join(root, ".heapscope", "sessions", sanitize(name))
+      @created_at = Time.now.utc
+      @reports = []
+    end
+
+    def ensure!
+      FileUtils.mkdir_p(@dir)
+      write_meta!
+      self
+    end
+
+    def record(report, label: nil)
+      label ||= "report-#{@reports.size + 1}"
+      path = File.join(@dir, "#{label}.json")
+      report.save(path)
+      html = File.join(@dir, "#{label}.html")
+      report.save_html(html)
+      entry = { label: label, path: path, html: html, at: Time.now.utc.iso8601, healthy: report.healthy? }
+      @reports << entry
+      write_meta!
+      entry
+    end
+
+    def measure(label: "measure", **opts, &block)
+      report = HeapScope.measure(**opts, &block)
+      record(report, label: label)
+      report
+    end
+
+    def retention_test(label: "retention", **opts, &block)
+      report = HeapScope.retention_test(**opts, &block)
+      record(report, label: label)
+      report
+    end
+
+    def latest
+      @reports.last
+    end
+
+    def self.list(root: Dir.pwd)
+      base = File.join(root, ".heapscope", "sessions")
+      return [] unless Dir.exist?(base)
+
+      Dir.children(base).sort.map do |name|
+        meta_path = File.join(base, name, "meta.json")
+        meta = File.exist?(meta_path) ? JSON.parse(File.read(meta_path), symbolize_names: true) : { name: name }
+        meta
+      end
+    end
+
+    private
+
+    def sanitize(name)
+      name.gsub(/[^a-zA-Z0-9_-]+/, "_")
+    end
+
+    def write_meta!
+      File.write(
+        File.join(@dir, "meta.json"),
+        JSON.pretty_generate(
+          name: @name,
+          id: @id,
+          created_at: @created_at.iso8601,
+          reports: @reports,
+          heapscope_version: VERSION
+        )
+      )
+    end
+  end
+end

data/lib/heapscope/sidekiq_middleware.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module HeapScope
+  # Optional Sidekiq server middleware. Does not require Sidekiq at load time.
+  class SidekiqMiddleware
+    def initialize(options = {})
+      @sample_rate = options.fetch(:sample_rate, 0.05)
+      @force_gc = options.fetch(:force_gc, false)
+      @mode = options.fetch(:mode, :lightweight)
+      @on_report = options[:on_report]
+    end
+
+    def call(worker, job, queue)
+      return yield if @sample_rate <= 0 || rand > @sample_rate
+
+      result = nil
+      report = HeapScope.measure(
+        force_gc: @force_gc,
+        mode: @mode,
+        metadata: {
+          kind: "sidekiq_job",
+          worker: worker.class.name,
+          queue: queue,
+          jid: job["jid"],
+          pid: Process.pid
+        }
+      ) do
+        result = yield
+        true
+      end
+
+      @on_report&.call(report)
+      result
+    end
+  end
+end

data/lib/heapscope/snapshot.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require "json"
+require "securerandom"
+require "time"
+
+module HeapScope
+  # Stable snapshot abstraction. Configurable fidelity — not a full heap dump.
+  class Snapshot
+    SCHEMA_VERSION = HeapScope::SCHEMA_VERSION
+    SLIM_CLASS_LIMIT = 40
+    SLIM_ALLOC_LIMIT = 20
+
+    attr_reader :id, :timestamp, :mode, :gc_stat, :rss_bytes, :class_stats,
+                :allocation_sites, :metadata, :limitations, :sampled,
+                :process, :duration_ms, :object_sample
+
+    def initialize(id:, timestamp:, mode:, gc_stat:, rss_bytes:, class_stats:,
+                   allocation_sites: {}, metadata: {}, limitations: [],
+                   sampled: false, process: {}, duration_ms: 0, object_sample: [])
+      @id = id
+      @timestamp = timestamp
+      @mode = mode
+      @gc_stat = gc_stat || {}
+      @rss_bytes = rss_bytes
+      @class_stats = class_stats || {}
+      @allocation_sites = allocation_sites || {}
+      @metadata = metadata || {}
+      @limitations = limitations || []
+      @sampled = sampled
+      @process = process || {}
+      @duration_ms = duration_ms
+      @object_sample = object_sample || []
+    end
+
+    def gc_generation
+      gc_stat[:count]
+    end
+
+    def heap_live_slots
+      gc_stat[:heap_live_slots]
+    end
+
+    def heap_free_slots
+      gc_stat[:heap_free_slots]
+    end
+
+    def total_allocated_objects
+      gc_stat[:total_allocated_objects]
+    end
+
+    def total_freed_objects
+      gc_stat[:total_freed_objects]
+    end
+
+    def class_count(name)
+      (class_stats[name.to_s] || {})[:count].to_i
+    end
+
+    def class_bytes(name)
+      (class_stats[name.to_s] || {})[:shallow_bytes].to_i
+    end
+
+    def top_classes(limit = 20, by: :count)
+      class_stats.values.sort_by { |s| -(s[by] || 0) }.first(limit)
+    end
+
+    def same_process?(other)
+      process[:pid] == other.process[:pid]
+    end
+
+    def to_h(slim: false)
+      stats = class_stats
+      sites = allocation_sites
+      sample = object_sample
+      meta = metadata.dup
+      limits = limitations.dup
+
+      if slim
+        top = top_classes(SLIM_CLASS_LIMIT)
+        stats = top.to_h { |row| [row[:name], row] }
+        sites =
+          if allocation_sites.is_a?(Hash)
+            allocation_sites.to_a.first(SLIM_ALLOC_LIMIT).to_h
+          else
+            Array(allocation_sites).first(SLIM_ALLOC_LIMIT)
+          end
+        sample = []
+        meta[:slim] = true
+        limits << "slim_json_truncated_classes" unless limits.include?("slim_json_truncated_classes")
+      end
+
+      {
+        schema_version: SCHEMA_VERSION,
+        heapscope_version: VERSION,
+        id: id,
+        timestamp: timestamp.iso8601(3),
+        mode: mode.to_s,
+        gc_stat: stringify_keys(gc_stat),
+        rss_bytes: rss_bytes,
+        class_stats: stats.transform_values { |v| stringify_keys(v) },
+        allocation_sites: sites,
+        metadata: meta,
+        limitations: limits,
+        sampled: sampled,
+        process: process,
+        duration_ms: duration_ms,
+        object_sample: sample
+      }
+    end
+
+    def to_json(*_args)
+      JSON.pretty_generate(to_h)
+    end
+
+    def save(path, slim: false)
+      File.write(path, JSON.pretty_generate(to_h(slim: slim)))
+      path
+    end
+
+    def self.load(path)
+      data = JSON.parse(File.read(path), symbolize_names: true)
+      from_h(data)
+    end
+
+    def self.from_h(data)
+      class_stats = (data[:class_stats] || {}).each_with_object({}) do |(name, stats), hash|
+        hash[name.to_s] = {
+          name: name.to_s,
+          count: stats[:count].to_i,
+          shallow_bytes: stats[:shallow_bytes].to_i,
+          average_bytes: stats[:average_bytes].to_f
+        }
+      end
+
+      new(
+        id: data[:id] || SecureRandom.hex(8),
+        timestamp: Time.parse(data[:timestamp].to_s),
+        mode: (data[:mode] || "standard").to_sym,
+        gc_stat: symbolize_keys(data[:gc_stat] || {}),
+        rss_bytes: data[:rss_bytes],
+        class_stats: class_stats,
+        allocation_sites: data[:allocation_sites] || {},
+        metadata: data[:metadata] || {},
+        limitations: data[:limitations] || [],
+        sampled: data[:sampled] || false,
+        process: data[:process] || {},
+        duration_ms: data[:duration_ms].to_f,
+        object_sample: data[:object_sample] || []
+      )
+    end
+
+    def self.stringify_keys(hash)
+      hash.each_with_object({}) { |(k, v), h| h[k.to_s] = v }
+    end
+
+    def self.symbolize_keys(hash)
+      hash.each_with_object({}) { |(k, v), h| h[k.to_sym] = v }
+    end
+
+    def stringify_keys(hash)
+      self.class.stringify_keys(hash)
+    end
+  end
+end