heapscope 0.6.0

data/Rakefile

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+  t.warning = false
+end
+
+begin
+  require "rubocop/rake_task"
+  RuboCop::RakeTask.new
+rescue LoadError
+  # rubocop optional until bundle install
+end
+
+desc "Run benchmarks"
+task :benchmark do
+  ruby "benchmark/run.rb"
+end
+
+desc "Run fixture evaluation harness"
+task :eval do
+  ruby "benchmark/eval_harness.rb"
+end
+
+desc "Open HeapScope console"
+task :console do
+  exec "ruby", "bin/console"
+end
+
+desc "Print diagnostic code catalog"
+task :codes do
+  require_relative "lib/heapscope"
+  puts HeapScope::Catalog.to_text
+end
+
+namespace :docs do
+  desc "Generate / print diagnostic code catalog for docs"
+  task :codes do
+    require_relative "lib/heapscope"
+    puts HeapScope::Catalog.to_text
+  end
+end
+
+task default: :test

data/SECURITY.md

@@ -0,0 +1,39 @@
+# Security Policy
+
+## Privacy posture
+
+HeapScope is a **local** diagnostics toolkit.
+
+- No network calls in normal operation
+- No telemetry, analytics, or automatic uploads
+- No serialization of object values by default
+- No dumping of `ENV`, credentials, tokens, cookies, or request bodies by default
+
+Memory inspection is inherently sensitive. Treat snapshots and reports as **confidential** if they were captured in environments that handle personal or secret data — even when values are redacted, class names and allocation sites can still leak product structure.
+
+## Supported versions
+
+| Version | Supported |
+|---------|-----------|
+| 0.6.x | ✅ |
+| 0.5.x | ✅ |
+| 0.4.x | ✅ (security fixes when practical) |
+| < 0.4 | ❌ |
+
+## Reporting a vulnerability
+
+Please open a GitHub Security Advisory or email the maintainers privately. Do **not** file a public issue that includes exploit details for unreleased flaws.
+
+We aim to acknowledge reports within 7 days.
+
+## Safe production use
+
+Prefer:
+
+```ruby
+HeapScope.configure do |config|
+  config.mode = :production_safe
+end
+```
+
+Avoid deep heap walks, forced GC, and value inspection on multi-tenant production hosts unless you fully understand the pause and privacy impact.

data/assets/logo.svg

@@ -0,0 +1,24 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" role="img" aria-label="HeapScope">
+  <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>
+    <linearGradient id="glass" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#ecfdf5"/>
+      <stop offset="100%" stop-color="#99f6e4"/>
+    </linearGradient>
+  </defs>
+  <rect width="256" height="256" rx="48" fill="url(#bg)"/>
+  <!-- heap blocks -->
+  <rect x="52" y="150" width="36" height="36" rx="4" fill="#5eead4" opacity="0.95"/>
+  <rect x="94" y="132" width="36" height="54" rx="4" fill="#99f6e4" opacity="0.95"/>
+  <rect x="136" y="114" width="36" height="72" rx="4" fill="#ccfbf1" opacity="0.95"/>
+  <rect x="72" y="108" width="28" height="28" rx="3" fill="#2dd4bf" opacity="0.9"/>
+  <rect x="108" y="90" width="28" height="28" rx="3" fill="#5eead4" opacity="0.9"/>
+  <!-- scope / magnifier -->
+  <circle cx="156" cy="96" r="42" fill="none" stroke="url(#glass)" stroke-width="14"/>
+  <circle cx="156" cy="96" r="26" fill="none" stroke="#0f766e" stroke-width="4" opacity="0.35"/>
+  <line x1="186" y1="126" x2="214" y2="154" stroke="#f8fafc" stroke-width="14" stroke-linecap="round"/>
+  <line x1="186" y1="126" x2="214" y2="154" stroke="#99f6e4" stroke-width="6" stroke-linecap="round"/>
+</svg>

data/assets/wordmark.svg

@@ -0,0 +1,18 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 720 160" role="img" aria-label="HeapScope">
+  <defs>
+    <linearGradient id="mark" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#0f766e"/>
+      <stop offset="100%" stop-color="#334155"/>
+    </linearGradient>
+  </defs>
+  <g transform="translate(8,16)">
+    <rect width="128" height="128" rx="28" fill="url(#mark)"/>
+    <rect x="26" y="78" width="18" height="18" rx="2" fill="#5eead4"/>
+    <rect x="48" y="68" width="18" height="28" rx="2" fill="#99f6e4"/>
+    <rect x="70" y="58" width="18" height="38" rx="2" fill="#ccfbf1"/>
+    <circle cx="78" cy="48" r="22" fill="none" stroke="#ecfdf5" stroke-width="8"/>
+    <line x1="94" y1="64" x2="110" y2="80" stroke="#ecfdf5" stroke-width="8" stroke-linecap="round"/>
+  </g>
+  <text x="160" y="98" font-family="IBM Plex Sans, Segoe UI, Helvetica, Arial, sans-serif" font-size="64" font-weight="650" fill="#0f172a" letter-spacing="-1.5">HeapScope</text>
+  <text x="164" y="128" font-family="IBM Plex Sans, Segoe UI, Helvetica, Arial, sans-serif" font-size="18" fill="#64748b" letter-spacing="0.5">Ruby retention &amp; heap growth diagnostics</text>
+</svg>

data/docs/README.md

@@ -0,0 +1,20 @@
+<p align="center">
+  <img src="../assets/wordmark.svg" alt="HeapScope" width="360"/>
+</p>
+
+# HeapScope docs
+
+Start at [`index.md`](index.md).
+
+- [CLI](cli.md)
+- [API](api/overview.md)
+- [Guides](guides/)
+- [Diagnostics](diagnostics/)
+- [Roadmap](ROADMAP.md)
+- [Changelogs](changelogs/)
+
+Website: [theworker02.github.io/heapscope](https://theworker02.github.io/heapscope/) · Sponsor: [thanks.dev/u/gh/theworker02](https://thanks.dev/u/gh/theworker02)
+
+<p align="center">
+  <img src="../assets/logo.svg" alt="" width="48"/>
+</p>

data/docs/ROADMAP.md

@@ -0,0 +1,29 @@
+# HeapScope roadmap
+
+## Current product (0.6)
+
+One coherent retention diagnostics toolkit: snapshots, diffs, multi-cycle experiments,
+ranked findings with next steps, budget presets, slim captures, watch alerts, sessions,
+report packs, and a modular CLI — all local-only.
+
+## Shipped history
+
+| Version | Theme |
+|---------|--------|
+| 0.1–0.3 | Core toolkit, detectors, aging/closures/dominators |
+| 0.4 | Sessions, scorecards, schema, GitHub polish |
+| 0.5 | Funding, Pages site, pack/suggest, CLI expansion |
+| **0.6** | Product consolidation — presets, ranking, watch, slim JSON, doctor --fix |
+
+## Next
+
+- Higher-fidelity dominators when runtime APIs allow
+- Packaged GitHub Action for baseline compare
+- Async/fiber-heavy runtime playbooks
+- Optional heap-dump importers
+
+## Non-goals
+
+- SaaS APM
+- “Confirmed leak” from noisy samples
+- Secret dumping / telemetry

data/docs/adr/0001-evidence-over-certainty.md

@@ -0,0 +1,24 @@
+# ADR 0001 — Evidence over certainty
+
+## Status
+
+Accepted
+
+## Context
+
+Memory tools often collapse observations into “leak detected,” which trains developers to distrust the tool when false positives appear.
+
+## Decision
+
+Every HeapScope finding MUST separate:
+
+1. Observed facts
+2. Derived behavior
+3. Hypothesis
+4. Suspected cause (optional, evidence-gated)
+
+Prefer severity categories (LOW/MEDIUM/HIGH) over unexplained confidence percentages.
+
+## Consequences
+
+Reports are longer and more careful. Users get fewer dramatic claims and more actionable investigation steps.

data/docs/adr/0002-local-only-privacy.md

@@ -0,0 +1,19 @@
+# ADR 0002 — Local-only privacy by default
+
+## Status
+
+Accepted
+
+## Context
+
+Heap contents may include credentials, PII, and request payloads.
+
+## Decision
+
+- No network / telemetry in the gem
+- No object value serialization by default
+- Explicit opt-in + redaction hooks for value inspection
+
+## Consequences
+
+HeapScope cannot offer hosted dashboards without a separate product decision. Privacy becomes a marketable feature.

data/docs/adr/0003-runtime-adapters.md

@@ -0,0 +1,25 @@
+# ADR 0003 — Runtime adapters (MRI-first)
+
+## Status
+
+Accepted
+
+## Context
+
+ObjectSpace APIs differ across MRI, JRuby, and TruffleRuby.
+
+## Decision
+
+Expose a capability matrix via adapters:
+
+```text
+HeapScope::Runtime::MRI
+HeapScope::Runtime::JRuby
+HeapScope::Runtime::TruffleRuby
+```
+
+Never pretend unavailable features exist.
+
+## Consequences
+
+Slightly more code, much safer degradation, and a clear extension point for future engines.

data/docs/adr/README.md

@@ -0,0 +1,7 @@
+# Architecture Decision Record index
+
+| ADR | Title |
+|-----|-------|
+| [0001](0001-evidence-over-certainty.md) | Evidence over certainty |
+| [0002](0002-local-only-privacy.md) | Local-only privacy by default |
+| [0003](0003-runtime-adapters.md) | Runtime adapters for MRI-first design |

data/docs/allocators.md

@@ -0,0 +1,13 @@
+# Allocator awareness
+
+HeapScope reports Ruby heap and RSS separately on purpose.
+
+| Allocator | Notes |
+|-----------|--------|
+| glibc malloc | Can retain free arenas; RSS may not fall after Ruby GC |
+| jemalloc | Often smoother; still not equal to Ruby heap size |
+| macOS allocator | Zone behavior can obscure release timing |
+
+Fragmentation indicators (RSS vs heap pages vs live/free slots) are reported **conservatively** as potential fragmentation — never "confirmed fragmentation."
+
+Copy-on-write after fork (Puma workers, prefork) can also change RSS without new Ruby object retention.

data/docs/api/overview.md

@@ -0,0 +1,70 @@
+# API overview
+
+Public entry points (see also the README and [`docs/index.md`](../index.md)):
+
+```ruby
+HeapScope.snapshot
+HeapScope.compare(before, after)
+HeapScope.measure(...) { }
+HeapScope.retention_test(...) { }
+HeapScope.experiment(...) { }
+HeapScope.repeat(n) { }
+HeapScope.probe(title: "…") { }       # scorecard + report
+HeapScope.session("name")             # .heapscope/sessions persistence
+HeapScope.scorecard(report)
+HeapScope.check_budget(budget:) { }
+HeapScope.check(budget:) { }          # raises BudgetExceededError
+HeapScope.capabilities
+HeapScope.doctor
+HeapScope.overhead(mode: :lightweight)
+HeapScope.codes
+HeapScope.about
+HeapScope.branding
+HeapScope.suggest_ignores(report)
+HeapScope.next_steps(report)
+HeapScope.budget_preset(:ci_strict)
+HeapScope.pack(report, "./out")
+HeapScope.write_config!("heapscope.yml")
+HeapScope.load_config!("heapscope.yml")
+HeapScope.configure { |c| }
+HeapScope.ignore_class(MyCache)
+HeapScope.after_warmup { }
+```
+
+Key types:
+
+| Class / module | Role |
+|----------------|------|
+| `Snapshot` | Point-in-time heap summary (`save(slim: true)`) |
+| `Diff` | Before/after comparison (+ `to_table`) |
+| `Report` | Findings + presentation (+ `scorecard`, `table`, `next_steps`) |
+| `Scorecard` / `Probe` | Executive verdict / one-shot measure |
+| `Session` | Named artifact folders |
+| `Finding` / `Findings` | Evidence-structured diagnostic + ranking |
+| `Budget` | CI gates + presets |
+| `Suggest` | Next steps + ignore hints |
+| `Monitor` | Sampling + optional anomaly alerts |
+| `Branding` | URLs, banners, asset paths |
+| `Budget` | CI thresholds |
+| `Monitor` | Interval sampler |
+| `TrendStore` | Historical samples |
+| `RetentionSession` | Multi-cycle tracker |
+| `Graph` | Bounded reachability |
+| `Detectors` | Thread-local / collection classifiers |
+| `Schema` | Report JSON validation |
+| `Catalog` | HS001–HS010 catalog |
+| `Branding` | Banner, funding, footers |
+| `Suggest` | Ignore-pattern recommendations |
+| `Pack` | Local report export bundles |
+| `Tables` | ASCII / Markdown tables |
+
+Optional requires:
+
+```ruby
+require "heapscope/cli"
+require "heapscope/middleware"
+require "heapscope/rails"
+require "heapscope/sidekiq_middleware"
+require "heapscope/rspec"
+require "heapscope/minitest"
+```

data/docs/changelogs/0.1.0.md

@@ -0,0 +1,22 @@
+# HeapScope 0.1.0
+
+**Release date:** 2026-08-12  
+**Theme:** First useful retention toolkit
+
+## Why 0.1.0 exists
+
+`top` and RSS charts tell you memory moved. HeapScope 0.1.0 tells you **which object populations moved**, whether they **survived GC**, and whether that looks like **churn or sticky retention** — without pretending to have a SaaS backend or magical leak certainty.
+
+## Shipped
+
+- Snapshots + diffs + measure + retention sessions
+- Findings HS001–HS010 with evidence structure
+- CLI + JSON/text/HTML reports
+- Optional Rails/Sidekiq/RSpec/Minitest surfaces
+- MRI-first runtime adapters with safe degradation
+
+## Honest limits
+
+- Deep reachability is bounded and approximate
+- Remote process attach is not implemented
+- Retained-size dominators are deferred to later milestones

data/docs/changelogs/0.2.0.md

@@ -0,0 +1,49 @@
+# HeapScope 0.2.0
+
+**Release date:** 2026-08-12  
+**Theme:** Milestone 2 foundations — detectors, branding, documentation depth
+
+## Highlights
+
+HeapScope 0.2 turns the Milestone 1 toolkit into something you can show a team:
+
+- Recognizable brand (logo + wordmark)
+- A long, badge-rich README that documents real workflows
+- Detectors that separate **cache plateaus** from **unbounded collections**
+- Thread-local retention findings for Puma/Sidekiq-style thread reuse
+- HTML reports that look like a product, not a debug dump
+
+## Detectors
+
+`HeapScope::Detectors` adds structured analysis on top of raw class series:
+
+| Signal | Outcome |
+|--------|---------|
+| Thread keys with large/shallow suspicious names | HS003 |
+| Monotonic Array/Hash/registry growth, no shrink | HS004 |
+| Plateau after growth | Likely cache (low severity) |
+
+## Documentation
+
+- Expanded README (TOC, compatibility matrix, privacy, architecture)
+- `SECURITY.md`, `CODE_OF_CONDUCT.md`
+- Guides under `docs/guides/`
+- This release note
+
+## Upgrade notes
+
+From 0.1.x:
+
+```ruby
+gem "heapscope", "~> 0.2"
+```
+
+API remains compatible. New fields may appear on retention reports (`collections`, `thread_locals`).
+
+## Verification
+
+```bash
+bundle exec rake test
+bundle exec rubocop
+gem build heapscope.gemspec
+```

data/docs/changelogs/0.3.0.md

@@ -0,0 +1,38 @@
+# HeapScope 0.3.0
+
+**Release date:** 2026-08-12  
+**Theme:** Fill every gap — aging, globals, closures, fibers, dominators, trends, doctor
+
+## Why 0.3.0 is “crazy complete”
+
+0.1 shipped the retention toolkit.  
+0.2 made it a product.  
+**0.3 fills the original blueprint gaps** so HeapScope feels like a full diagnostics system:
+
+| Area | Added |
+|------|-------|
+| Aging | Coarse young/middle/long-lived buckets from multi-cycle survival |
+| Globals | Global/constant registry inventory + growth findings |
+| Closures | Opt-in Proc retained-size hypotheses (HS006) |
+| Fibers | Fiber storage inventory |
+| Dominators | Approximate top retainers from thread-locals |
+| Fragmentation | Conservative RSS/heap ratio indicator |
+| Noise | Framework noise defaults (Zeitwerk/Bootsnap/…) |
+| Config | YAML loader (`heapscope.yml`) |
+| Notifications | Optional AS::Notifications growth probe |
+| Paths | Tree formatter for retention paths |
+| Reproduction | Commands embedded in reports |
+| Overhead | Self-profiling API + CLI |
+| Doctor | Runtime/capability health CLI |
+| Trends | `TrendStore` + `heapscope trends` |
+| Reports | Markdown export |
+| Matchers | Richer RSpec/Minitest helpers |
+| Rails | `measure_action`, AR population helper |
+
+## Upgrade
+
+```ruby
+gem "heapscope", "~> 0.3"
+```
+
+Closure detection remains **off by default** (`detect_closures: false`) because Proc walks are expensive.

data/docs/changelogs/0.4.0.md

@@ -0,0 +1,32 @@
+# HeapScope 0.4.0
+
+**Release date:** 2026-08-13  
+**Theme:** Professional DX — sessions, scorecards, schema, GitHub polish
+
+## Highlights
+
+HeapScope 0.4 makes the project feel like a maintained open-source product:
+
+### Product features
+
+- **`HeapScope.probe`** — one-shot workload probe with executive scorecard
+- **`HeapScope.session`** — named `.heapscope/sessions` artifact folders (JSON + HTML)
+- **`Scorecard`** — compact CI/console verdict card
+- **`Tables`** — ASCII/Markdown class-growth tables
+- **`Schema`** — report JSON validation (`heapscope validate`)
+- **`Catalog`** — `heapscope codes` diagnostic encyclopedia dump
+- CLI: `sessions`, `history`, `validate`, `codes`
+- `bin/console` + Rake `:console`, `:codes`, `:eval`
+
+### Professional repo surface
+
+- Issue / PR templates, Dependabot
+- Docs hub (`docs/index.md`) + CLI reference
+- Gem post-install message
+- Expanded changelog / roadmap
+
+## Upgrade
+
+```ruby
+gem "heapscope", "~> 0.4"
+```

data/docs/changelogs/0.5.0.md

@@ -0,0 +1,18 @@
+# HeapScope 0.5.0
+
+Funding, Pages site, and packaging polish.
+
+## Highlights
+
+- **FUNDING.yml** — GitHub Sponsors + thanks.dev at `u/gh/theworker02`
+- **GitHub Pages** — branded landing site at `site/` deployed via Actions
+- **`heapscope about` / `HeapScope.about`** — docs + sponsor links
+- **`heapscope suggest`** — ignore-pattern recommendations (manual review only)
+- **`heapscope pack`** — offline JSON + HTML + Markdown report bundles
+- Report footers and doctor output link to thanks.dev and the docs site
+
+## Enable GitHub Pages
+
+1. Push to `main` (or `master`)
+2. Repo **Settings → Pages → Source: GitHub Actions**
+3. Site URL: `https://theworker02.github.io/heapscope/`

data/docs/changelogs/0.6.0.md

@@ -0,0 +1,23 @@
+# HeapScope 0.6.0 — Professional product release
+
+**Date:** 2026-08-13 · **Owner:** [@theworker02](https://github.com/theworker02)
+
+0.6 folds the 0.4–0.5 DX work into one coherent product narrative: ranked findings,
+actionable next steps, CI budget presets, slim snapshots, smarter watch/monitor alerts,
+and a doctor that can write a local starter config — without stacking parallel “v2” APIs.
+
+## Highlights
+
+- **Budget presets** — `rails_request`, `sidekiq_job`, `ci_strict` via `Budget.preset` / `HeapScope.budget_preset`
+- **Finding ranking & dedupe** — `Findings.rank_and_dedupe` applied in the analyzer and retention reports
+- **Next-steps engine** — `Suggest.next_steps` / `HeapScope.next_steps` surfaces prioritized follow-ups in text, Markdown, HTML, and CLI `suggest`
+- **`heapscope watch`** — monitor alias with anomaly alerts on RSS / live-slot spikes
+- **Slim JSON snapshots** — `snapshot.save(..., slim: true)` / `heapscope snapshot --slim`
+- **`heapscope doctor --fix`** — writes a starter `heapscope.yml` (local only)
+- **Ownership cleanup** — `Probe`/`Scorecard` in `scorecard.rb`; `ConfigLoader` in `config.rb`; framework noise hints owned by `Noise`
+
+## Links
+
+- Gem: [rubygems.org/gems/heapscope](https://rubygems.org/gems/heapscope)
+- Docs: [theworker02.github.io/heapscope](https://theworker02.github.io/heapscope/)
+- Sponsor: [thanks.dev/u/gh/theworker02](https://thanks.dev/u/gh/theworker02)

data/docs/cli.md

@@ -0,0 +1,98 @@
+<p align="center">
+  <img src="../assets/wordmark.svg" alt="HeapScope" width="360"/>
+</p>
+
+# CLI reference
+
+```bash
+heapscope [global options] <command> [options]
+```
+
+## Global options
+
+| Flag | Description |
+|------|-------------|
+| `--verbose` | Verbose HeapScope logging |
+| `--quiet` | Suppress non-essential output |
+| `--config PATH` | Load YAML/Ruby config before the command |
+| `--json` | Prefer machine-readable JSON on key commands |
+| `--no-color` / `--color` | Disable or force ANSI colors (also respects `NO_COLOR`) |
+| `-h`, `--help` | Show help |
+| `-v`, `--version` | Print version |
+
+Per-command help: `heapscope help <command>` or `heapscope <command> --help`.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `snapshot` | Capture heap snapshot JSON (`--slim` for compact) |
+| `inspect` | Inspect current process or saved capture |
+| `diff` | Diff two snapshots (scorecard + table + report) |
+| `monitor` | Interval sampling (`--alert` for spikes) |
+| `watch` | Monitor with anomaly alerts enabled |
+| `trends` | Print monitor timeline |
+| `report` | Render text / html / markdown / json |
+| `baseline` | Create baseline from report |
+| `compare` | Baseline vs current (CI exit codes) |
+| `sessions` | List `.heapscope/sessions` |
+| `history` | Recent session artifacts |
+| `validate` | Validate report schema |
+| `suggest` / `ignore-suggest` | Next steps + ignore_patterns (never auto-applied) |
+| `pack` / `export` | Export local JSON+HTML+Markdown bundle |
+| `probe` | Measure a `--file` / `--eval` workload → scorecard |
+| `measure` | CLI wrapper around `HeapScope.measure` |
+| `retention` | CLI wrapper around `HeapScope.retention_test` |
+| `findings` | List/filter ranked findings |
+| `scorecard` | Print scorecard only from a report |
+| `table` | Print growth table from a report |
+| `explain` | Diagnostic encyclopedia entry |
+| `open` / `html` | Write HTML and print path |
+| `self-test` | Built-in intentional retention demo |
+| `env` | Print relevant environment variables |
+| `completion` | Generate bash / zsh / powershell completion |
+| `man` | Extended about + examples |
+| `codes` | Print HS001–HS010 catalog |
+| `doctor` | Runtime + config health (`--fix` writes starter YAML) |
+| `overhead` | Snapshot overhead microbench |
+| `config` | Load YAML/Ruby config |
+| `about` | Branding, docs, and funding links |
+| `capabilities` | Capability matrix |
+| `version` | Print version |
+| `help` | Global or per-command help |
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | Regression / finding above threshold (`--fail-on-*`) |
+| 2 | Invalid input / configuration |
+| 3 | Capability unavailable |
+
+## Notable flags
+
+- `snapshot`: `--slim`, `--mode`, `--force-gc`, `--track-allocations`
+- `monitor` / `watch`: `--alert`, `--rss-alert-bytes`, `--live-alert-slots`
+- `doctor`: `--fix`, `--config-out PATH`, `--force`
+- `suggest`: `--json` (next_steps + ignore_patterns), `--ignores-only`
+- Analysis commands: `--fail-on-high`, `--fail-on-medium`, `--fail-on LEVEL`
+
+## Examples
+
+```bash
+heapscope about
+heapscope doctor --fix
+heapscope snapshot --slim -o before.json
+heapscope diff before.json after.json --html out.html --fail-on-medium
+heapscope watch --duration 120 -o watch.json
+heapscope suggest report.json
+heapscope pack report.json -o ./pack
+heapscope explain HS001
+```
+
+Sponsor: https://thanks.dev/u/gh/theworker02 · Site: https://theworker02.github.io/heapscope/
+
+<p align="center">
+  <img src="../assets/logo.svg" alt="" width="48"/>
+</p>