heapscope 0.6.0

data/lib/heapscope/growth.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module HeapScope
+  # Detects growth patterns across samples. Evidence-based, not magical.
+  module Growth
+    module_function
+
+    PATTERNS = %i[
+      stable bursty linear_growth monotonic_growth sawtooth
+      exponential_like bounded_plateau insufficient_data
+    ].freeze
+
+    def analyze(samples)
+      values = samples.map(&:to_f)
+      return result(:insufficient_data, values) if values.size < 3
+
+      slope = linear_slope(values)
+      variance = sample_variance(values)
+      mean = values.sum / values.size
+      recovering = sawtooth?(values)
+      plateau = plateau?(values)
+      monotonic = monotonic?(values)
+      exponential = exponential_like?(values)
+
+      relative_span = mean.positive? ? (values.max - values.min) / mean : 0
+
+      pattern =
+        if recovering
+          :sawtooth
+        elsif plateau && values.max > values.first * 1.5
+          :bounded_plateau
+        elsif exponential
+          :exponential_like
+        elsif monotonic && slope > 0 && !exponential
+          :monotonic_growth
+        elsif relative_span < 0.05 || (slope.abs < [mean * 0.02, 1.0].max && variance < (mean * 0.05)**2)
+          :stable
+        elsif slope > 0
+          :linear_growth
+        elsif variance > (mean * 0.3)**2
+          :bursty
+        else
+          :stable
+        end
+
+      result(pattern, values, slope: slope)
+    end
+
+    def result(pattern, values, slope: 0.0)
+      {
+        pattern: pattern,
+        slope: slope.round(3),
+        samples: values,
+        min: values.min,
+        max: values.max,
+        mean: values.empty? ? 0.0 : (values.sum / values.size).round(3),
+        recovery_after_gc: pattern == :sawtooth ? :observed : :minimal
+      }
+    end
+
+    def linear_slope(values)
+      n = values.size
+      xs = (0...n).map(&:to_f)
+      x_mean = xs.sum / n
+      y_mean = values.sum / n
+      num = xs.zip(values).sum { |x, y| (x - x_mean) * (y - y_mean) }
+      den = xs.sum { |x| (x - x_mean)**2 }
+      return 0.0 if den.zero?
+
+      num / den
+    end
+
+    def sample_variance(values)
+      return 0.0 if values.size < 2
+
+      mean = values.sum / values.size
+      values.sum { |v| (v - mean)**2 } / (values.size - 1)
+    end
+
+    def monotonic?(values)
+      values.each_cons(2).all? { |a, b| b >= a }
+    end
+
+    def sawtooth?(values)
+      drops = values.each_cons(2).count { |a, b| b < a * 0.7 }
+      rises = values.each_cons(2).count { |a, b| b > a }
+      drops >= 1 && rises >= 2
+    end
+
+    def plateau?(values)
+      return false if values.size < 5
+
+      last = values.last(3)
+      span = last.max - last.min
+      early_growth = values[2] >= values.first * 1.5
+      span <= [last.max * 0.05, 2].max && early_growth
+    end
+
+    def exponential_like?(values)
+      return false unless monotonic?(values) && values.first.positive?
+      return false if values.size < 4
+
+      ratios = values.each_cons(2).map { |a, b| a.positive? ? b / a : 0 }
+      # Require accelerating growth, not merely a steady linear climb.
+      ratios.size >= 3 && ratios.all? { |r| r >= 1.4 } && ratios.last >= ratios.first
+    end
+  end
+end

data/lib/heapscope/middleware.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module HeapScope
+  # Opt-in Rack middleware. Lightweight sampling only — never full heap on every request.
+  class Middleware
+    def initialize(app, sample_rate: 0.01, force_gc: false, mode: :lightweight, on_report: nil)
+      @app = app
+      @sample_rate = sample_rate
+      @force_gc = force_gc
+      @mode = mode
+      @on_report = on_report
+    end
+
+    def call(env)
+      return @app.call(env) if @sample_rate <= 0 || rand > @sample_rate
+
+      status = headers = body = nil
+      report = HeapScope.measure(
+        force_gc: @force_gc,
+        mode: @mode,
+        metadata: {
+          kind: "rack_request",
+          path: env["PATH_INFO"],
+          method: env["REQUEST_METHOD"],
+          pid: Process.pid
+        }
+      ) do
+        status, headers, body = @app.call(env)
+        true
+      end
+      @on_report&.call(report)
+      [status, headers, body]
+    end
+  end
+end

data/lib/heapscope/minitest.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "heapscope"
+
+# Optional Minitest helpers: require "heapscope/minitest"
+module HeapScope
+  module Minitest
+    def assert_heapscope_retained_under(limit, force_gc: true, klass: nil, &block)
+      report = HeapScope.measure(force_gc: force_gc, &block)
+      actual = klass ? report.retained_count_for(klass) : report.diff&.surviving_estimate.to_i
+      assert actual < limit,
+             "expected retained objects < #{limit}, got #{actual}. " \
+             "Suspects: #{report.suspects.first(5).map { |s| s[:name] }.join(', ')}"
+      report
+    end
+
+    def assert_heapscope_bytes_under(limit, force_gc: true, &block)
+      report = HeapScope.measure(force_gc: force_gc, &block)
+      actual = report.diff&.heap_bytes_estimate_delta.to_i
+      assert actual < limit,
+             "expected retained bytes < #{limit}, got #{actual}"
+      report
+    end
+
+    def assert_heapscope_budget(budget, **opts, &)
+      report = HeapScope.check_budget(budget: budget, **opts, &)
+      assert report.passed_budget?, report.budget_result[:violations].join("\n")
+      report
+    end
+
+    def assert_heapscope_healthy(force_gc: true, &block)
+      report = HeapScope.measure(force_gc: force_gc, &block)
+      assert report.healthy? || report.findings.none? { |f| f.severity == :high },
+             "expected healthy profile, got #{report.findings.map(&:code)}"
+      report
+    end
+
+    def assert_heapscope_no_code(code, force_gc: true, &block)
+      report = HeapScope.measure(force_gc: force_gc, &block)
+      refute report.findings.any? { |f| f.code == code },
+             "expected no #{code}, got #{report.findings.map(&:code)}"
+      report
+    end
+  end
+end
+
+Minitest::Test.include HeapScope::Minitest if defined?(Minitest::Test)

data/lib/heapscope/monitor.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module HeapScope
+  # In-process sampling monitor with optional anomaly alerts.
+  # Uses a low-priority background thread.
+  class Monitor
+    Sample = Struct.new(:at, :snapshot, keyword_init: true)
+    Alert = Struct.new(:at, :kind, :message, :rss_delta, :live_delta, keyword_init: true)
+
+    attr_reader :samples, :interval, :mode, :alerts
+
+    def self.start(interval: 10, mode: :lightweight, max_samples: 1_000,
+                   alert: false, rss_alert_bytes: 25 * 1024 * 1024, live_alert_slots: 80_000)
+      new(
+        interval: interval,
+        mode: mode,
+        max_samples: max_samples,
+        alert: alert,
+        rss_alert_bytes: rss_alert_bytes,
+        live_alert_slots: live_alert_slots
+      ).tap(&:start)
+    end
+
+    def initialize(interval: 10, mode: :lightweight, max_samples: 1_000,
+                   alert: false, rss_alert_bytes: 25 * 1024 * 1024, live_alert_slots: 80_000)
+      @interval = interval
+      @mode = mode
+      @max_samples = max_samples
+      @alert = alert
+      @rss_alert_bytes = rss_alert_bytes
+      @live_alert_slots = live_alert_slots
+      @samples = []
+      @alerts = []
+      @thread = nil
+      @stop = false
+      @collector = Collector.new
+    end
+
+    def alert?
+      @alert
+    end
+
+    def start
+      return self if @thread&.alive?
+
+      @stop = false
+      @thread = Thread.new do
+        Thread.current.name = "heapscope-monitor" if Thread.current.respond_to?(:name=)
+        Thread.current.abort_on_exception = false
+        until @stop
+          begin
+            snap = @collector.capture(mode: @mode, metadata: { monitor: true })
+            sample = Sample.new(at: Time.now.utc, snapshot: snap)
+            maybe_alert!(sample)
+            @samples << sample
+            @samples.shift if @samples.size > @max_samples
+          rescue StandardError => e
+            HeapScope.config.log(:debug, "monitor sample failed: #{e.message}")
+          end
+          sleep @interval
+        end
+      end
+      self
+    end
+
+    def stop
+      @stop = true
+      @thread&.join(2)
+      @thread = nil
+      finish_report
+    end
+
+    def finish_report
+      if samples.empty?
+        return Report.new(
+          summary: { healthy: true, samples: 0 },
+          metadata: { kind: "monitor", alerts: [] }
+        )
+      end
+
+      session_like = samples.map(&:snapshot)
+      first = session_like.first
+      last = session_like.last
+      diff = Diff.new(first, last)
+      analysis = Analyzer.new.analyze_diff(diff)
+      series = build_timeline
+      alert_payload = alerts.map(&:to_h)
+      Report.from_diff(
+        diff,
+        analysis: analysis,
+        metadata: {
+          kind: "monitor",
+          timeline: series,
+          alerts: alert_payload,
+          alert_count: alert_payload.size
+        }
+      )
+    end
+
+    private
+
+    def maybe_alert!(sample)
+      return unless @alert
+      return if samples.empty?
+
+      prev = samples.last.snapshot
+      rss_delta = safe_delta(sample.snapshot.rss_bytes, prev.rss_bytes)
+      live_delta = safe_delta(sample.snapshot.heap_live_slots, prev.heap_live_slots)
+
+      if rss_delta && rss_delta >= @rss_alert_bytes
+        record_alert!(
+          :rss_spike,
+          "RSS rose by #{rss_delta} bytes between samples (threshold #{@rss_alert_bytes}).",
+          rss_delta: rss_delta,
+          live_delta: live_delta
+        )
+      end
+
+      return unless live_delta && live_delta >= @live_alert_slots
+
+      record_alert!(
+        :live_slots_spike,
+        "Heap live slots rose by #{live_delta} between samples (threshold #{@live_alert_slots}).",
+        rss_delta: rss_delta,
+        live_delta: live_delta
+      )
+    end
+
+    def record_alert!(kind, message, rss_delta:, live_delta:)
+      alert = Alert.new(
+        at: Time.now.utc.iso8601,
+        kind: kind,
+        message: message,
+        rss_delta: rss_delta,
+        live_delta: live_delta
+      )
+      @alerts << alert
+      HeapScope.config.log(:info, "monitor alert: #{kind} — #{message}")
+      warn("[HeapScope watch] #{kind}: #{message}") if $stderr.tty? && !HeapScope.config.quiet
+    end
+
+    def safe_delta(after_v, before_v)
+      return nil if after_v.nil? || before_v.nil?
+
+      after_v - before_v
+    end
+
+    def build_timeline
+      samples.map do |s|
+        top = s.snapshot.top_classes(1).first
+        {
+          time: s.at.iso8601,
+          rss_bytes: s.snapshot.rss_bytes,
+          live_slots: s.snapshot.heap_live_slots,
+          top_class: top && top[:name]
+        }
+      end
+    end
+  end
+end

data/lib/heapscope/noise.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module HeapScope
+  # Known framework / VM noise filters. Affects findings, not raw snapshot data.
+  module Noise
+    DEFAULT_PATTERNS = [
+      /^RubyVM/,
+      /^Zeitwerk/,
+      /^Bootsnap/,
+      /^ActiveSupport::Dependencies/,
+      /^Module$/,
+      /^Class$/,
+      /^HeapScope::/
+    ].freeze
+
+    # Extra framework hints used by Suggest (never auto-applied to config).
+    FRAMEWORK_HINTS = [
+      /^ActiveSupport::/,
+      /^ActiveRecord::ConnectionAdapters/,
+      /^ActionDispatch::/,
+      /^ActionController::/,
+      /^ActionView::/,
+      /^Rack::/,
+      /^Sidekiq::/,
+      /^Concurrent::/
+    ].freeze
+
+    module_function
+
+    def default_patterns
+      DEFAULT_PATTERNS.dup
+    end
+
+    def suggestion_patterns
+      DEFAULT_PATTERNS + FRAMEWORK_HINTS
+    end
+
+    def noisy?(name, patterns: HeapScope.config.ignore_patterns)
+      patterns.any? { |p| name.to_s.match?(p) }
+    end
+
+    def apply_defaults!
+      DEFAULT_PATTERNS.each do |pattern|
+        HeapScope.config.ignore_patterns << pattern unless HeapScope.config.ignore_patterns.include?(pattern)
+      end
+    end
+  end
+end

data/lib/heapscope/notifications.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module HeapScope
+  # Optional ActiveSupport::Notifications adapter — not required in core.
+  module Notifications
+    module_function
+
+    def available?
+      defined?(ActiveSupport::Notifications)
+    end
+
+    def subscriber_counts
+      raise CapabilityError, "ActiveSupport::Notifications not loaded" unless available?
+
+      # Best-effort: AS does not always expose a public subscriber registry.
+      # We sample notifier internals when present, otherwise return empty.
+      notifier = ActiveSupport::Notifications.notifier
+      counts = Hash.new(0)
+      if notifier.respond_to?(:listeners_for)
+        # Can't enumerate all patterns easily — return structure placeholder
+        { note: "Use listen_growth to track specific patterns over time." }
+      elsif notifier.instance_variable_defined?(:@subscribers)
+        Array(notifier.instance_variable_get(:@subscribers)).each do |sub|
+          pattern = begin
+            sub.respond_to?(:pattern) ? sub.pattern : sub.class.name
+          rescue StandardError
+            "unknown"
+          end
+          counts[pattern.to_s] += 1
+        end
+        counts
+      else
+        { note: "Subscriber registry not introspectable on this Rails version." }
+      end
+    end
+
+    # Track a specific notification pattern count via wrapping — records samples.
+    class GrowthProbe
+      def initialize(pattern)
+        @pattern = pattern
+        @samples = []
+        @count = 0
+        @sub = nil
+      end
+
+      def start!
+        raise CapabilityError, "ActiveSupport::Notifications not loaded" unless Notifications.available?
+
+        @sub = ActiveSupport::Notifications.subscribe(@pattern) { @_count = (@_count || 0) + 1 }
+        self
+      end
+
+      def sample!
+        # Prefer explicit counter if subscribe block used; otherwise inventory
+        @samples << (@_count || 0)
+        @samples.last
+      end
+
+      def finish
+        ActiveSupport::Notifications.unsubscribe(@sub) if @sub
+        series = @samples
+        trend = Growth.analyze(series)
+        finding =
+          if %i[monotonic_growth linear_growth exponential_like].include?(trend[:pattern])
+            Finding.new(
+              code: "HS005",
+              severity: :high,
+              subject: @pattern.to_s,
+              facts: ["Observed fact: notification #{@pattern} sample counts #{series.inspect}."],
+              derived: ["Derived: pattern=#{trend[:pattern]}."],
+              hypothesis: "Possible repeated registration without unsubscribe.",
+              suggestions: ["Register subscribers once at boot", "Unsubscribe on teardown"]
+            )
+          end
+        { series: series, trend: trend, finding: finding }
+      end
+    end
+  end
+end

data/lib/heapscope/pack.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+
+module HeapScope
+  # Export a self-contained local report bundle (JSON + HTML + Markdown + notes).
+  # Never uploads; writes only to the destination directory.
+  module Pack
+    module_function
+
+    def export(report, dir, label: "heapscope-report")
+      FileUtils.mkdir_p(dir)
+      base = File.join(dir, label)
+      json_path = "#{base}.json"
+      html_path = "#{base}.html"
+      md_path = "#{base}.md"
+      readme_path = File.join(dir, "README.txt")
+
+      report.save(json_path)
+      File.write(html_path, Report::HTML.render(report))
+      File.write(md_path, report.to_markdown)
+      File.write(readme_path, readme_body(report, label: label))
+
+      {
+        dir: dir,
+        json: json_path,
+        html: html_path,
+        markdown: md_path,
+        readme: readme_path
+      }
+    end
+
+    def readme_body(report, label:)
+      lines = []
+      lines << Branding.compact_banner
+      lines << ""
+      lines << "Local report bundle: #{label}"
+      lines << "Generated: #{Time.now.utc.iso8601}"
+      lines << "Result: #{report.summary[:healthy] ? 'HEALTHY' : 'ATTENTION'}"
+      lines << "Findings: #{report.findings.size}"
+      lines << ""
+      lines << "Files:"
+      lines << "  #{label}.json       — machine-readable report"
+      lines << "  #{label}.html       — shareable HTML (local file)"
+      lines << "  #{label}.md         — Markdown summary"
+      lines << ""
+      lines << "This bundle was generated offline. It was not uploaded anywhere."
+      lines << ""
+      Branding.funding_lines.each { |l| lines << l }
+      lines.join("\n")
+    end
+    private_class_method :readme_body
+  end
+end

data/lib/heapscope/paths.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module HeapScope
+  # Pretty retention-path formatting and reproduction helpers.
+  module Paths
+    module_function
+
+    def format_tree(path)
+      return "Nearest observed retainer: unavailable" if path.nil? || Array(path.nodes).empty?
+
+      lines = []
+      lines << "LIKELY RETENTION PATH (confidence: #{path.confidence})"
+      lines << "Note: #{path.note}" if path.note
+      Array(path.nodes).each_with_index do |node, idx|
+        via = node[:via] || node["via"] || node[:note] || "ref"
+        prefix = idx.zero? ? "" : "#{"  " * idx}└── "
+        lines << "#{prefix}#{via}"
+      end
+      lines.join("\n")
+    end
+  end
+
+  module Reproduction
+    module_function
+
+    def command(metadata = {})
+      mode = metadata[:mode] || HeapScope.config.mode
+      script = metadata[:script] || "examples/import_leak.rb"
+      "HEAPSCOPE_MODE=#{mode} bundle exec ruby #{script}"
+    end
+
+    def attach!(report, metadata = {})
+      report.instance_variable_set(
+        :@reproduction,
+        {
+          command: command(metadata),
+          metadata: metadata,
+          captured_at: Time.now.utc.iso8601
+        }
+      )
+      report
+    end
+  end
+
+  # Self-overhead profiler to avoid HeapScope dominating the workload.
+  module Overhead
+    module_function
+
+    def measure_snapshot(mode: :lightweight, runs: 3)
+      times = runs.times.map do
+        t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        snap = HeapScope.snapshot(mode: mode, max_objects: 50_000)
+        elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0
+        { seconds: elapsed, duration_ms: snap.duration_ms, classes: snap.class_stats.size }
+      end
+      {
+        mode: mode,
+        runs: times,
+        avg_seconds: (times.sum { |t| t[:seconds] } / times.size).round(4),
+        note: "HeapScope overhead for this mode on this machine."
+      }
+    end
+  end
+end

data/lib/heapscope/rails.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module HeapScope
+  # Optional Rails helpers. Loaded explicitly: require "heapscope/rails"
+  module Rails
+    module_function
+
+    def install_middleware!(sample_rate: 0.01)
+      raise CapabilityError, "Rails is not loaded" unless defined?(::Rails)
+
+      ::Rails.application.config.middleware.use(
+        HeapScope::Middleware,
+        sample_rate: sample_rate
+      )
+    end
+
+    def request_retention(label: "request", cycles: 10, force_gc: true, &block)
+      raise ArgumentError, "block required" unless block_given?
+
+      HeapScope.retention_test(
+        cycles: cycles,
+        force_gc: force_gc,
+        metadata: { kind: "rails_request", label: label }, &block
+      )
+    end
+
+    def measure_action(controller:, action:, force_gc: true, &block)
+      raise ArgumentError, "block required" unless block_given?
+
+      HeapScope.measure(
+        force_gc: force_gc,
+        metadata: {
+          kind: "rails_action",
+          controller: controller.to_s,
+          action: action.to_s,
+          label: "#{controller}##{action}"
+        }, &block
+      )
+    end
+
+    def activerecord_population
+      return {} unless defined?(::ActiveRecord::Base)
+
+      counts = {}
+      ObjectSpace.each_object(Class) do |klass|
+        next unless klass < ::ActiveRecord::Base
+        next if klass.abstract_class?
+
+        counts[klass.name] = ObjectSpace.each_object(klass).count
+      rescue StandardError
+        next
+      end
+      counts
+    rescue StandardError
+      {}
+    end
+
+    def warn_if_autoloading!
+      return unless defined?(::Rails)
+      return unless ::Rails.respond_to?(:application)
+      return unless ::Rails.env.development?
+
+      HeapScope.config.log(
+        :verbose,
+        "Rails development autoloading can distort heap growth. Prefer warmups or cache_classes for experiments."
+      )
+    end
+  end
+end
+
+require_relative "middleware"