RubyGems - heapscope - Versions diffs - 0.6.0 - Mend

heapscope 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (110) hide show

checksums.yaml +7 -0
data/.rubocop.yml +119 -0
data/CHANGELOG.md +86 -0
data/CODE_OF_CONDUCT.md +38 -0
data/CONTRIBUTING.md +72 -0
data/Gemfile +11 -0
data/LICENSE +21 -0
data/README.md +342 -0
data/Rakefile +49 -0
data/SECURITY.md +39 -0
data/assets/heapscope-logo.png +0 -0
data/assets/logo.svg +24 -0
data/assets/wordmark.svg +18 -0
data/docs/README.md +20 -0
data/docs/ROADMAP.md +29 -0
data/docs/adr/0001-evidence-over-certainty.md +24 -0
data/docs/adr/0002-local-only-privacy.md +19 -0
data/docs/adr/0003-runtime-adapters.md +25 -0
data/docs/adr/README.md +7 -0
data/docs/allocators.md +13 -0
data/docs/api/overview.md +70 -0
data/docs/changelogs/0.1.0.md +22 -0
data/docs/changelogs/0.2.0.md +49 -0
data/docs/changelogs/0.3.0.md +38 -0
data/docs/changelogs/0.4.0.md +32 -0
data/docs/changelogs/0.5.0.md +18 -0
data/docs/changelogs/0.6.0.md +23 -0
data/docs/cli.md +98 -0
data/docs/diagnostics/HS001_persistent_class_growth.md +39 -0
data/docs/diagnostics/HS002_high_retention_ratio.md +24 -0
data/docs/diagnostics/HS003_thread_local_retention.md +24 -0
data/docs/diagnostics/HS004_unbounded_collection.md +19 -0
data/docs/diagnostics/HS005_callback_accumulation.md +14 -0
data/docs/diagnostics/HS006_closure_retention.md +15 -0
data/docs/diagnostics/HS007_poor_gc_recovery.md +18 -0
data/docs/diagnostics/HS008_baseline_regression.md +15 -0
data/docs/diagnostics/HS009_high_allocation_pressure.md +13 -0
data/docs/diagnostics/HS010_native_memory_mismatch.md +19 -0
data/docs/guides/ci-budgets.md +43 -0
data/docs/guides/first-retention-experiment.md +25 -0
data/docs/guides/production-safe.md +17 -0
data/docs/index.md +38 -0
data/examples/cache_vs_leak.rb +30 -0
data/examples/closure_capture.rb +20 -0
data/examples/healthy_churn.rb +16 -0
data/examples/heapscope.yml +12 -0
data/examples/import_leak.rb +19 -0
data/examples/probe_and_session.rb +22 -0
data/examples/thread_local_leak.rb +31 -0
data/exe/heapscope +7 -0
data/heapscope.gemspec +73 -0
data/lib/heapscope/aging.rb +114 -0
data/lib/heapscope/analyzer.rb +333 -0
data/lib/heapscope/baseline.rb +77 -0
data/lib/heapscope/branding.rb +98 -0
data/lib/heapscope/budget.rb +108 -0
data/lib/heapscope/capabilities.rb +42 -0
data/lib/heapscope/catalog.rb +71 -0
data/lib/heapscope/cli/color.rb +67 -0
data/lib/heapscope/cli/commands/capture.rb +289 -0
data/lib/heapscope/cli/commands/diffing.rb +157 -0
data/lib/heapscope/cli/commands/meta.rb +244 -0
data/lib/heapscope/cli/commands/reporting.rb +228 -0
data/lib/heapscope/cli/completion.rb +72 -0
data/lib/heapscope/cli/help.rb +226 -0
data/lib/heapscope/cli/support.rb +126 -0
data/lib/heapscope/cli.rb +165 -0
data/lib/heapscope/closures.rb +102 -0
data/lib/heapscope/collector.rb +167 -0
data/lib/heapscope/config.rb +196 -0
data/lib/heapscope/detectors.rb +131 -0
data/lib/heapscope/diff.rb +130 -0
data/lib/heapscope/dominators.rb +87 -0
data/lib/heapscope/errors.rb +13 -0
data/lib/heapscope/extrapolation.rb +51 -0
data/lib/heapscope/findings.rb +149 -0
data/lib/heapscope/globals.rb +108 -0
data/lib/heapscope/graph.rb +218 -0
data/lib/heapscope/growth.rb +108 -0
data/lib/heapscope/middleware.rb +35 -0
data/lib/heapscope/minitest.rb +47 -0
data/lib/heapscope/monitor.rb +160 -0
data/lib/heapscope/noise.rb +48 -0
data/lib/heapscope/notifications.rb +79 -0
data/lib/heapscope/pack.rb +55 -0
data/lib/heapscope/paths.rb +64 -0
data/lib/heapscope/rails.rb +71 -0
data/lib/heapscope/report/html.rb +283 -0
data/lib/heapscope/report/markdown.rb +78 -0
data/lib/heapscope/report/text.rb +204 -0
data/lib/heapscope/report.rb +308 -0
data/lib/heapscope/retention.rb +91 -0
data/lib/heapscope/rspec.rb +118 -0
data/lib/heapscope/runtime/base.rb +130 -0
data/lib/heapscope/runtime/jruby.rb +28 -0
data/lib/heapscope/runtime/mri.rb +86 -0
data/lib/heapscope/runtime/truffleruby.rb +40 -0
data/lib/heapscope/runtime/windows_rss.rb +75 -0
data/lib/heapscope/runtime.rb +33 -0
data/lib/heapscope/schema.rb +28 -0
data/lib/heapscope/scorecard.rb +85 -0
data/lib/heapscope/session.rb +90 -0
data/lib/heapscope/sidekiq_middleware.rb +36 -0
data/lib/heapscope/snapshot.rb +165 -0
data/lib/heapscope/suggest.rb +99 -0
data/lib/heapscope/tables.rb +58 -0
data/lib/heapscope/trend_store.rb +41 -0
data/lib/heapscope/version.rb +6 -0
data/lib/heapscope.rb +307 -0
metadata +211 -0

data/lib/heapscope/report/html.rb ADDED Viewed

@@ -0,0 +1,283 @@
+# frozen_string_literal: true
+require "json"
+module HeapScope
+  class Report
+    # Static HTML report — no backend required. Charts use inline SVG sparkline bars.
+    module HTML
+      module_function
+      def render(report)
+        data = report.to_h
+        <<~HTML
+          <!DOCTYPE html>
+          <html lang="en">
+          <head>
+            <meta charset="utf-8">
+            <meta name="viewport" content="width=device-width, initial-scale=1">
+            <title>HeapScope Report — #{escape(report.summary[:healthy] ? "HEALTHY" : "ATTENTION")}</title>
+            <style>
+              :root {
+                --bg0: #f4f7f6;
+                --bg1: #e8eef0;
+                --ink: #14201c;
+                --muted: #5b6b66;
+                --accent: #0f766e;
+                --accent2: #334155;
+                --card: #ffffffcc;
+                --high: #b91c1c;
+                --med: #c2410c;
+                --low: #57534e;
+                --ok: #047857;
+              }
+              * { box-sizing: border-box; }
+              body {
+                margin: 0;
+                font-family: "IBM Plex Sans", "Segoe UI", sans-serif;
+                color: var(--ink);
+                background:
+                  radial-gradient(1200px 600px at 10% -10%, #ccfbf1 0%, transparent 55%),
+                  radial-gradient(900px 500px at 100% 0%, #e2e8f0 0%, transparent 50%),
+                  linear-gradient(165deg, var(--bg0), var(--bg1));
+                min-height: 100vh;
+              }
+              header.hero {
+                padding: 2.5rem 1.25rem 1.5rem;
+                max-width: 1040px;
+                margin: 0 auto;
+                display: grid;
+                grid-template-columns: 72px 1fr;
+                gap: 1.25rem;
+                align-items: center;
+              }
+              header.hero svg { width: 72px; height: 72px; }
+              h1 {
+                font-family: "IBM Plex Serif", Georgia, serif;
+                font-weight: 650;
+                letter-spacing: -0.03em;
+                font-size: clamp(2rem, 4vw, 2.75rem);
+                margin: 0;
+              }
+              .tagline { color: var(--muted); margin: 0.35rem 0 0; }
+              main { max-width: 1040px; margin: 0 auto; padding: 0 1.25rem 4rem; }
+              .banner {
+                padding: 1rem 1.25rem;
+                background: var(--card);
+                backdrop-filter: blur(8px);
+                border-left: 5px solid var(--accent);
+                border-radius: 0 12px 12px 0;
+                margin: 1rem 0 1.5rem;
+              }
+              .banner.ok { border-left-color: var(--ok); }
+              .banner.warn { border-left-color: var(--med); }
+              h2 {
+                margin-top: 2.25rem;
+                font-size: 0.85rem;
+                color: var(--accent);
+                text-transform: uppercase;
+                letter-spacing: 0.08em;
+              }
+              .grid {
+                display: grid;
+                grid-template-columns: repeat(auto-fit, minmax(180px, 1fr));
+                gap: 0.75rem;
+              }
+              .stat {
+                background: var(--card);
+                border-radius: 12px;
+                padding: 1rem;
+                border: 1px solid #d6e0dc;
+              }
+              .stat .label { font-size: 0.75rem; color: var(--muted); text-transform: uppercase; letter-spacing: 0.05em; }
+              .stat .value { font-size: 1.35rem; font-weight: 600; margin-top: 0.25rem; }
+              table { width: 100%; border-collapse: collapse; background: var(--card); border-radius: 12px; overflow: hidden; }
+              th, td { text-align: left; padding: 0.55rem 0.7rem; border-bottom: 1px solid #e4ebe8; font-size: 0.92rem; }
+              th { background: #f0f5f3; font-size: 0.75rem; text-transform: uppercase; letter-spacing: 0.04em; color: var(--muted); }
+              .sev-high { color: var(--high); font-weight: 650; }
+              .sev-medium { color: var(--med); font-weight: 600; }
+              .sev-low { color: var(--low); }
+              .bars { display: flex; align-items: flex-end; gap: 3px; height: 48px; margin: 0.5rem 0 1rem; }
+              .bars span {
+                display: block;
+                width: 10px;
+                background: linear-gradient(180deg, #2dd4bf, #0f766e);
+                border-radius: 3px 3px 0 0;
+                min-height: 2px;
+              }
+              pre {
+                background: #0f172a;
+                color: #e2e8f0;
+                padding: 1rem;
+                overflow: auto;
+                font-size: 0.78rem;
+                border-radius: 12px;
+                max-height: 420px;
+              }
+              .note { font-size: 0.85rem; color: var(--muted); }
+              footer { margin-top: 3rem; color: var(--muted); font-size: 0.85rem; }
+              @media (max-width: 640px) {
+                header.hero { grid-template-columns: 1fr; }
+              }
+            </style>
+          </head>
+          <body>
+            <header class="hero">
+              #{logo_svg}
+              <div>
+                <h1>HeapScope</h1>
+                <p class="tagline">Retention-first diagnostics · v#{escape(report.heapscope_version)} · Ruby #{escape(report.runtime_info[:ruby])} · schema #{report.schema_version}</p>
+              </div>
+            </header>
+            <main>
+              <div class="banner #{report.summary[:healthy] ? "ok" : "warn"}">
+                <strong>#{report.summary[:healthy] ? "HEALTHY" : "ATTENTION"}</strong>
+                <div class="note">#{escape(Scorecard.from_report(report).to_text.lines[2..5]&.join(' ') || 'Estimates are approximate.')}</div>
+                <div class="note">Object values are not included by default. Facts ≠ hypotheses.</div>
+              </div>
+              <h2>Memory overview</h2>
+              <div class="grid">
+                <div class="stat"><div class="label">RSS before</div><div class="value">#{bytes(report.before&.rss_bytes)}</div></div>
+                <div class="stat"><div class="label">RSS after</div><div class="value">#{bytes(report.after&.rss_bytes)}</div></div>
+                <div class="stat"><div class="label">RSS Δ</div><div class="value">#{bytes(report.diff&.rss_delta)}</div></div>
+                <div class="stat"><div class="label">Live slots Δ</div><div class="value">#{report.diff&.heap_live_delta || "n/a"}</div></div>
+                <div class="stat"><div class="label">Retention</div><div class="value">#{ratio(report.diff&.retention_ratio)}</div></div>
+                <div class="stat"><div class="label">Findings</div><div class="value">#{report.findings.size}</div></div>
+              </div>
+              #{sparkline_section(report)}
+              <h2>Top class growth</h2>
+              <table>
+                <tr><th>Class</th><th>Before</th><th>After</th><th>Delta</th><th>Bytes Δ</th></tr>
+                #{class_rows(report)}
+              </table>
+              <h2>Top suspects</h2>
+              #{suspect_blocks(report)}
+              <h2>Findings</h2>
+              #{finding_blocks(report)}
+              <h2>Next steps</h2>
+              #{next_step_blocks(report)}
+              <h2>Limitations</h2>
+              <p class="note">#{report.limitations.empty? ? "None recorded." : escape(report.limitations.join(", "))}</p>
+              <h2>Raw JSON</h2>
+              <pre>#{escape(JSON.pretty_generate(data))}</pre>
+              <footer>
+                #{Branding.html_footer}
+              </footer>
+            </main>
+          </body>
+          </html>
+        HTML
+      end
+      def logo_svg
+        inline = Branding.logo_svg_inline
+        return inline if inline && !inline.strip.empty?
+        <<~SVG
+          <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" aria-hidden="true">
+            <defs>
+              <linearGradient id="bg" x1="0%" y1="0%" x2="100%" y2="100%">
+                <stop offset="0%" stop-color="#0f766e"/><stop offset="100%" stop-color="#334155"/>
+              </linearGradient>
+            </defs>
+            <rect width="256" height="256" rx="48" fill="url(#bg)"/>
+            <rect x="52" y="150" width="36" height="36" rx="4" fill="#5eead4"/>
+            <rect x="94" y="132" width="36" height="54" rx="4" fill="#99f6e4"/>
+            <rect x="136" y="114" width="36" height="72" rx="4" fill="#ccfbf1"/>
+            <circle cx="156" cy="96" r="42" fill="none" stroke="#ecfdf5" stroke-width="14"/>
+            <line x1="186" y1="126" x2="214" y2="154" stroke="#ecfdf5" stroke-width="14" stroke-linecap="round"/>
+          </svg>
+        SVG
+      end
+      def next_step_blocks(report)
+        steps = Suggest.next_steps(report)
+        return "<p class='note'>No prioritized next steps.</p>" if steps.empty?
+        items = steps.map.with_index do |step, i|
+          tag = step[:code] ? escape(step[:code]) : "hint"
+          "<li><strong>#{i + 1}. [#{tag}]</strong> #{escape(step[:action])}</li>"
+        end.join
+        "<ol>#{items}</ol>"
+      end
+      def sparkline_section(report)
+        series = report.retention && report.retention[:class_series]
+        return "" unless series && !series.empty?
+        top = series.first
+        vals = Array(top[:series]).map(&:to_f)
+        return "" if vals.empty?
+        max = vals.max.nonzero? || 1
+        bars = vals.map { |v| "<span style='height:#{[(v / max * 48).round, 2].max}px'></span>" }.join
+        <<~HTML
+          <h2>Retention sparkline — #{escape(top[:name])}</h2>
+          <div class="bars">#{bars}</div>
+          <p class="note">Sample series: #{escape(vals.map(&:to_i).inspect)} · pattern #{escape(top.dig(:trend, :pattern).to_s)}</p>
+        HTML
+      end
+      def class_rows(report)
+        rows = report.diff ? report.diff.growing_classes(20) : []
+        return "<tr><td colspan='5'>No growth data</td></tr>" if rows.empty?
+        rows.map do |c|
+          "<tr><td>#{escape(c[:name])}</td><td>#{c[:before_count]}</td><td>#{c[:after_count]}</td>" \
+            "<td>#{c[:delta_count]}</td><td>#{bytes(c[:delta_bytes])}</td></tr>"
+        end.join("\n")
+      end
+      def suspect_blocks(report)
+        return "<p class='note'>No ranked suspects.</p>" if report.suspects.empty?
+        rows = report.suspects.first(10).map.with_index do |s, i|
+          "<tr><td>#{i + 1}</td><td>#{escape(s[:name])}</td>" \
+            "<td class='sev-#{s[:severity]}'>#{s[:severity].to_s.upcase}</td>" \
+            "<td>+#{s[:delta_count]}</td><td>#{escape(s[:classification].to_s)}</td></tr>"
+        end.join
+        "<table><tr><th>#</th><th>Class</th><th>Severity</th><th>Delta</th><th>Class</th></tr>#{rows}</table>"
+      end
+      def finding_blocks(report)
+        return "<p class='note'>No findings.</p>" if report.findings.empty?
+        report.findings.map do |f|
+          <<~BLOCK
+            <div class="banner">
+              <div class="sev-#{f.severity}">#{f.code} — #{escape(f.title)}</div>
+              <ul>#{f.facts.map { |x| "<li>#{escape(x)}</li>" }.join}</ul>
+              #{f.hypothesis ? "<p>#{escape(f.hypothesis)}</p>" : ""}
+              #{f.suspected_cause ? "<p class='note'>Suspected cause: #{escape(f.suspected_cause)}</p>" : ""}
+            </div>
+          BLOCK
+        end.join
+      end
+      def bytes(n)
+        return "n/a" if n.nil?
+        format("%.2f MB", n.to_f / (1024 * 1024))
+      end
+      def ratio(n)
+        return "n/a" if n.nil?
+        format("%.2f%%", n * 100.0)
+      end
+      def escape(str)
+        str.to_s.gsub("&", "&amp;").gsub("<", "&lt;").gsub(">", "&gt;")
+      end
+    end
+  end
+end

data/lib/heapscope/report/markdown.rb ADDED Viewed

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+module HeapScope
+  class Report
+    module Markdown
+      module_function
+      def render(report)
+        lines = []
+        lines << "# HeapScope Report"
+        lines << ""
+        lines << "- **Version:** #{report.heapscope_version}"
+        lines << "- **Ruby:** #{report.runtime_info[:ruby]} (#{report.runtime_info[:engine]})"
+        lines << "- **Result:** #{report.summary[:healthy] ? "HEALTHY" : "ATTENTION"}"
+        lines << ""
+        if report.before && report.after
+          lines << "## Memory"
+          lines << ""
+          lines << "| Metric | Before | After | Delta |"
+          lines << "|--------|--------|-------|-------|"
+          lines << "| RSS | #{mb(report.before.rss_bytes)} | #{mb(report.after.rss_bytes)} | #{mb(report.diff&.rss_delta)} |"
+          lines << "| Live slots | #{report.before.heap_live_slots} | #{report.after.heap_live_slots} | #{report.diff&.heap_live_delta} |"
+          lines << ""
+        end
+        if report.diff
+          lines << "## Top class growth"
+          lines << ""
+          lines << "| Class | Before | After | Delta | Bytes Δ |"
+          lines << "|-------|--------|-------|-------|---------|"
+          report.diff.growing_classes(15).each do |c|
+            lines << "| `#{c[:name]}` | #{c[:before_count]} | #{c[:after_count]} | #{c[:delta_count]} | #{mb(c[:delta_bytes])} |"
+          end
+          lines << ""
+        end
+        unless report.findings.empty?
+          lines << "## Findings"
+          lines << ""
+          report.findings.each do |f|
+            lines << "### #{f.code} — #{f.title} (`#{f.severity}`)"
+            f.facts.each { |fact| lines << "- Fact: #{fact}" }
+            f.derived.each { |d| lines << "- Derived: #{d}" }
+            lines << "- Hypothesis: #{f.hypothesis}" if f.hypothesis
+            lines << "- Suspected cause: #{f.suspected_cause}" if f.suspected_cause
+            lines << ""
+          end
+        end
+        if report.reproduction
+          lines << "## Reproduction"
+          lines << ""
+          lines << "```bash"
+          lines << report.reproduction[:command].to_s
+          lines << "```"
+          lines << ""
+        end
+        steps = Suggest.next_steps(report)
+        unless steps.empty?
+          lines << "## Next steps"
+          lines << ""
+          steps.each_with_index do |step, i|
+            tag = step[:code] || "hint"
+            lines << "#{i + 1}. **[#{tag}]** #{step[:action]}"
+          end
+          lines << ""
+        end
+        lines << "_Privacy: object values are not serialized by default._"
+        lines << ""
+        lines << "_#{Branding.report_footer}_"
+        lines.join("\n")
+      end
+      def mb(n)
+        return "n/a" if n.nil?
+        format("%.2f MB", n.to_f / (1024 * 1024))
+      end
+    end
+  end
+end

data/lib/heapscope/report/text.rb ADDED Viewed

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+module HeapScope
+  class Report
+    module Text
+      module_function
+      def render(report)
+        lines = []
+        lines << "╔══════════════════════════════════════════╗"
+        lines << "║              HEAPSCOPE REPORT            ║"
+        lines << "╚══════════════════════════════════════════╝"
+        lines << "Ruby: #{report.runtime_info[:ruby]} (#{report.runtime_info[:engine]})"
+        lines << "HeapScope: #{report.heapscope_version}"
+        lines << ""
+        if report.summary[:healthy]
+          lines << "Result: HEALTHY"
+          lines << "Peak object growth occurred during workload may have been reclaimed."
+          lines << "Persistent class growth: none significant." if report.findings.none? { |f| f.code == "HS001" }
+        else
+          lines << "Result: ATTENTION"
+        end
+        lines << ""
+        if report.before && report.after
+          lines << "RSS"
+          lines << "  Before: #{mb(report.before.rss_bytes)}"
+          lines << "  After:  #{mb(report.after.rss_bytes)}"
+          lines << "  Delta:  #{mb_delta(report.diff&.rss_delta)}"
+          lines << ""
+          lines << "Ruby Heap (live slots)"
+          lines << "  Before: #{fmt(report.before.heap_live_slots)}"
+          lines << "  After:  #{fmt(report.after.heap_live_slots)}"
+          lines << "  Delta:  #{signed(report.diff&.heap_live_delta)}"
+          lines << ""
+        end
+        if report.diff
+          ratio = report.diff.retention_ratio
+          lines << "Allocated Δ: #{fmt(report.diff.allocated_delta)}"
+          lines << "Freed Δ:     #{fmt(report.diff.freed_delta)}"
+          lines << "Surviving ≈: #{fmt(report.diff.surviving_estimate)}"
+          lines << "Retention:   #{ratio ? format('%.2f%%', ratio * 100) : 'n/a'}"
+          lines << ""
+          lines << "TOP CLASS GROWTH"
+          lines << "CLASS                            BEFORE      AFTER      DELTA      BYTES Δ"
+          report.diff.growing_classes(15).each do |c|
+            lines << format("%-28s %10s %10s %10s %12s",
+                            truncate(c[:name], 28),
+                            fmt(c[:before_count]),
+                            fmt(c[:after_count]),
+                            signed(c[:delta_count]),
+                            mb_delta(c[:delta_bytes]))
+          end
+          lines << ""
+        end
+        if report.retention
+          lines << "RETENTION SESSION"
+          lines << "  Samples: #{report.retention[:samples]}"
+          lines << "  Force GC: #{report.retention[:force_gc]}"
+          Array(report.retention[:persistent]).first(10).each do |entry|
+            lines << "  #{entry[:name]}: #{entry[:series].inspect} (#{entry[:trend][:pattern]}, slope #{entry[:trend][:slope]})"
+          end
+          lines << ""
+        end
+        unless report.suspects.empty?
+          lines << "TOP SUSPECTS"
+          report.suspects.first(8).each_with_index do |s, i|
+            lines << "  #{i + 1}. #{s[:name]}  #{s[:severity].to_s.upcase}"
+            lines << "     +#{s[:delta_count]} retained  class=#{s[:classification]}"
+          end
+          lines << ""
+        end
+        unless report.findings.empty?
+          lines << "FINDINGS"
+          report.findings.each do |f|
+            lines << "  #{f.code} — #{f.title} [#{f.severity.to_s.upcase}]"
+            f.facts.each { |fact| lines << "    Fact: #{fact}" }
+            f.derived.each { |d| lines << "    Derived: #{d}" }
+            lines << "    Hypothesis: #{f.hypothesis}" if f.hypothesis
+            lines << "    Suspected cause: #{f.suspected_cause}" if f.suspected_cause
+            f.suggestions.each { |s| lines << "    → #{s}" }
+            lines << ""
+          end
+        end
+        unless report.limitations.empty?
+          lines << "LIMITATIONS"
+          report.limitations.each { |l| lines << "  - #{l}" }
+          lines << ""
+        end
+        if report.budget_result
+          lines << "BUDGET: #{report.budget_result[:passed] ? 'PASS' : 'FAIL'}"
+          Array(report.budget_result[:violations]).each { |v| lines << "  - #{v}" }
+          lines << ""
+        end
+        if report.fragmentation
+          lines << "FRAGMENTATION INDICATOR"
+          lines << "  Status: #{report.fragmentation[:status]}"
+          lines << "  RSS/heap ratio ≈ #{report.fragmentation[:rss_to_heap_ratio]}"
+          lines << "  #{report.fragmentation[:note]}"
+          lines << ""
+        end
+        if report.aging && !report.aging.empty?
+          lines << "OBJECT AGING (coarse)"
+          report.aging.first(8).each do |row|
+            lines << "  #{row[:class]}  bucket=#{row[:bucket]}  survived=#{row[:survived_ratio]}  series=#{row[:series].inspect}"
+          end
+          lines << "  Note: coarse multi-cycle survival buckets — not exact ages."
+          lines << ""
+        end
+        if report.retention_paths && !report.retention_paths.empty?
+          lines << "RETENTION PATHS / RETAINERS"
+          report.retention_paths.each do |block|
+            lines << "  #{block[:summary]}"
+            Array(block[:retainers]).each do |r|
+              lines << "    - #{r[:class]} approx_retained=#{r[:approx_retained]} (#{r[:note]})"
+            end
+          end
+          lines << ""
+        end
+        if report.dominators && !report.dominators.empty?
+          lines << "APPROXIMATE TOP RETAINERS"
+          report.dominators.first(5).each do |d|
+            name = d.respond_to?(:class_name) ? d.class_name : d[:class_name]
+            retained = d.respond_to?(:approx_retained) ? d.approx_retained : d[:approx_retained]
+            lines << "  #{name}: approx retained #{retained}"
+          end
+          lines << ""
+        end
+        if report.reproduction
+          lines << "REPRODUCTION"
+          lines << "  #{report.reproduction[:command]}"
+          lines << ""
+        end
+        steps = Suggest.next_steps(report)
+        unless steps.empty?
+          lines << "NEXT STEPS"
+          steps.each_with_index do |step, i|
+            tag = step[:code] ? "[#{step[:code]}]" : "[hint]"
+            lines << "  #{i + 1}. #{tag} #{step[:action]}"
+          end
+          lines << ""
+        end
+        alerts = report.metadata[:alerts] || report.metadata["alerts"]
+        if alerts && !alerts.empty?
+          lines << "MONITOR ALERTS"
+          Array(alerts).each do |a|
+            kind = a[:kind] || a["kind"]
+            msg = a[:message] || a["message"]
+            lines << "  - #{kind}: #{msg}"
+          end
+          lines << ""
+        end
+        lines << "Privacy: object values are not serialized by default."
+        Branding.funding_lines.each { |l| lines << l }
+        lines << Branding.report_footer
+        lines.join("\n")
+      end
+      def mb(bytes)
+        return "n/a" if bytes.nil?
+        format("%.2f MB", bytes.to_f / (1024 * 1024))
+      end
+      def mb_delta(bytes)
+        return "n/a" if bytes.nil?
+        sign = bytes.positive? ? "+" : ""
+        format("%s%.2f MB", sign, bytes.to_f / (1024 * 1024))
+      end
+      def fmt(n)
+        return "n/a" if n.nil?
+        n.to_s.reverse.gsub(/(\d{3})(?=\d)/, '\\1,').reverse
+      end
+      def signed(n)
+        return "n/a" if n.nil?
+        n.positive? ? "+#{fmt(n)}" : fmt(n)
+      end
+      def truncate(str, len)
+        str.length > len ? "#{str[0, len - 1]}…" : str
+      end
+    end
+  end
+end