Module: HeapScope::CLI::Help

Defined in:

lib/heapscope/cli/help.rb

Overview

Help text and per-command usage.

Constant Summary

COMMANDS =

{
  "snapshot" => "Capture a heap snapshot to JSON",
  "inspect" => "Inspect current process (embedded) or a saved capture",
  "diff" => "Diff two snapshots (scorecard + table + report)",
  "monitor" => "Sample the current process for a duration",
  "watch" => "Monitor with anomaly alerts enabled (alias)",
  "trends" => "Summarize a monitor/report timeline",
  "report" => "Render a text/HTML/markdown/JSON report",
  "compare" => "Compare a baseline to a current report",
  "baseline" => "Create a baseline from a report",
  "sessions" => "List saved .heapscope sessions",
  "history" => "Show recent session reports",
  "validate" => "Validate a report JSON schema",
  "suggest" => "Suggest ignore_patterns from a report",
  "ignore-suggest" => "Alias of suggest",
  "pack" => "Export a local JSON+HTML+Markdown report bundle",
  "export" => "Alias of pack",
  "probe" => "Measure a Ruby file/snippet and print a scorecard",
  "measure" => "CLI wrapper around HeapScope.measure",
  "retention" => "CLI wrapper around HeapScope.retention_test",
  "flamegraph" => "Export allocation sites as folded stacks or Speedscope JSON",
  "findings" => "List/filter findings from a report",
  "scorecard" => "Print scorecard only from a report",
  "table" => "Print growth table from a report",
  "explain" => "Print diagnostic encyclopedia entry for a code",
  "open" => "Write HTML for a report and print the path",
  "html" => "Alias of open",
  "self-test" => "Run a built-in retention demo and show findings",
  "env" => "Print HeapScope-relevant environment variables",
  "completion" => "Generate bash/zsh/powershell completion scripts",
  "man" => "Extended about + examples",
  "codes" => "List diagnostic codes (HS001–HS010)",
  "doctor" => "Diagnose runtime capabilities & config",
  "overhead" => "Measure HeapScope snapshot overhead",
  "config" => "Load a YAML/Ruby config file",
  "about" => "Branding, docs, and funding links",
  "capabilities" => "Show runtime capabilities",
  "version" => "Print version",
  "help" => "Show help (or help <command>)"
}.freeze

USAGE =

{
  "snapshot" => <<~U,
  "inspect" => <<~U,
  "diff" => <<~U,
  "monitor" => <<~U,
  "watch" => <<~U,
  "probe" => <<~U,
  "measure" => <<~U,
  "retention" => <<~U,
  "flamegraph" => <<~U,
  "findings" => <<~U,
  "scorecard" => "Usage: heapscope scorecard REPORT.json [--json] [--title NAME]\n",
  "table" => "Usage: heapscope table REPORT.json [--markdown] [--top N]\n",
  "explain" => "Usage: heapscope explain CODE\n\nExample: heapscope explain HS001\n",
  "open" => "Usage: heapscope open REPORT.json [-o out.html]\n",
  "html" => "Usage: heapscope html REPORT.json [-o out.html]\n",
  "self-test" => "Usage: heapscope self-test [--json] [-o report.json]\n\nRuns a built-in intentional retention demo (local only).\n",
  "env" => "Usage: heapscope env [--json]\n",
  "completion" => "Usage: heapscope completion bash|zsh|powershell\n",
  "man" => "Usage: heapscope man\n\nExtended branding, privacy notes, and examples.\n",
  "pack" => <<~U,
  "export" => "Alias of pack. See: heapscope help pack\n",
  "suggest" => <<~U,
  "ignore-suggest" => "Alias of suggest. See: heapscope help suggest\n",
  "report" => <<~U,
  "baseline" => "Usage: heapscope baseline create REPORT.json -o baseline.json\n",
  "compare" => <<~U,
  "codes" => "Usage: heapscope codes\n",
  "doctor" => <<~U,
    Usage: heapscope doctor [options]
      --json                   Machine-readable doctor payload
      --fix                   Write starter heapscope.yml
      --config-out PATH        Path for --fix (default ./heapscope.yml)
      --force                  Overwrite existing config with --fix
  U
  "overhead" => "Usage: heapscope overhead [--mode MODE] [--runs N] [--json]\n",
  "config" => "Usage: heapscope config PATH\n",
  "about" => "Usage: heapscope about [--json]\n",
  "capabilities" => "Usage: heapscope capabilities [--json]\n",
  "sessions" => "Usage: heapscope sessions\n",
  "history" => "Usage: heapscope history [--limit N]\n",
  "validate" => "Usage: heapscope validate REPORT.json\n",
  "trends" => "Usage: heapscope trends REPORT.json\n",
  "version" => "Usage: heapscope version\n",
  "help" => "Usage: heapscope help [command]\n"
}.freeze

Class Method Summary

• .command_help(name) ⇒ Object
• .global_help ⇒ Object

Class Method Details

.command_help(name) ⇒ Object

# File 'lib/heapscope/cli/help.rb', line 87

def command_help(name)
  key = name.to_s
  desc = COMMANDS[key]
  return nil unless desc

  body = USAGE.fetch(key, "Usage: heapscope #{key} [options]\n\n#{desc}")
  "#{Branding.compact_banner}\n\n#{body}\n"
end

.global_help ⇒ Object

# File 'lib/heapscope/cli/help.rb', line 50

def global_help
  lines = []
  lines << Branding.compact_banner
  lines << ""
  lines << "Usage:"
  lines << "  heapscope [global options] <command> [options]"
  lines << ""
  lines << "Global options:"
  lines << "  --verbose          Verbose HeapScope logging"
  lines << "  --quiet            Suppress non-essential output"
  lines << "  --config PATH      Load YAML/Ruby config before command"
  lines << "  --json             Prefer machine-readable JSON on key commands"
  lines << "  --no-color         Disable ANSI colors"
  lines << "  --color            Force ANSI colors"
  lines << "  -h, --help         Show help"
  lines << "  -v, --version      Print version"
  lines << ""
  lines << "Commands:"
  COMMANDS.each do |name, desc|
    lines << format("  %-14s %s", name, desc)
  end
  lines << ""
  lines << "Exit codes:"
  lines << "  0 success"
  lines << "  1 regression / finding above threshold"
  lines << "  2 invalid input/configuration"
  lines << "  3 runtime capability unavailable"
  lines << ""
  lines << "Privacy: no network, no telemetry, no object value serialization by default."
  lines << "Gem:     #{Branding::RUBYGEMS_URL}"
  lines << "Sponsor: #{Branding::THANKS_DEV_URL}"
  lines << "Docs:    #{Branding::PAGES_URL}"
  lines << ""
  lines << "Try: heapscope help <command>   or   heapscope <command> --help"
  lines.join("\n")
end