heapscope 0.6.0

data/lib/heapscope/cli/help.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+module HeapScope
+  class CLI
+    # Help text and per-command usage.
+    module Help
+      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",
+        "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
+
+      module_function
+
+      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 << "Sponsor: #{Branding::THANKS_DEV_URL}"
+        lines << "Docs:    #{Branding::PAGES_URL}"
+        lines << ""
+        lines << "Try: heapscope help <command>   or   heapscope <command> --help"
+        lines.join("\n")
+      end
+
+      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
+
+      USAGE = {
+        "snapshot" => <<~U,
+          Usage: heapscope snapshot [options]
+            --mode MODE              lightweight|standard|deep
+            -o, --output PATH        Output JSON path
+            --slim                   Slim JSON (top classes / truncated sites)
+            --force-gc               Force GC before capture
+            --track-allocations      Enable allocation tracing for this capture
+        U
+        "inspect" => <<~U,
+          Usage: heapscope inspect [capture.json] [options]
+            --mode MODE              Snapshot mode when inspecting live process
+            --top N                  Limit class rows in derived views
+            --html PATH              Also write HTML
+            --markdown               Print Markdown instead of text
+            --json                   Print JSON
+            --fail-on-high           Exit 1 on HIGH findings
+        U
+        "diff" => <<~U,
+          Usage: heapscope diff BEFORE.json AFTER.json [options]
+            -o, --output PATH        Write report JSON
+            --html PATH              Write HTML report
+            --markdown               Print Markdown report body
+            --top N                  Limit growth table rows
+            --scorecard-only         Print scorecard only
+            --fail-on-high           Exit 1 if HIGH findings
+            --fail-on-medium         Exit 1 if MEDIUM or HIGH
+            --json                   Print report JSON
+        U
+        "monitor" => <<~U,
+          Usage: heapscope monitor [options]
+            --interval SEC           Sample interval (min 2)
+            --duration SEC           Total duration
+            --mode MODE              lightweight|standard
+            --alert                  Emit RSS / live-slot spike alerts
+            --rss-alert-bytes N      RSS delta threshold (default 25MB)
+            --live-alert-slots N     Live-slot delta threshold
+            -o, --output PATH        Report JSON path
+            --html PATH              Also write HTML
+            --fail-on-high           Exit 1 on HIGH findings
+        U
+        "watch" => <<~U,
+          Usage: heapscope watch [options]
+            Same as `monitor`, with --alert enabled by default.
+        U
+        "probe" => <<~U,
+          Usage: heapscope probe --file script.rb [options]
+                 heapscope probe --eval 'ruby code' [options]
+            --file PATH              Load Ruby file inside measured block
+            --eval CODE              Eval Ruby snippet inside measured block
+            --title NAME             Scorecard title
+            --mode MODE              Snapshot mode
+            --force-gc / --no-force-gc
+            -o, --output PATH        Save report JSON
+            --html PATH              Save HTML
+            --json                   Print JSON report
+        U
+        "measure" => <<~U,
+          Usage: heapscope measure --file script.rb [options]
+            --file PATH / --eval CODE
+            --mode MODE --force-gc --recovery-wait SEC
+            --track-allocations
+            -o, --output PATH --html PATH --json
+            --fail-on-high / --fail-on-medium
+        U
+        "retention" => <<~U,
+          Usage: heapscope retention --file script.rb [options]
+            --cycles N               Retention cycles (default 5)
+            --file PATH / --eval CODE
+            --mode MODE --force-gc / --no-force-gc
+            -o, --output PATH --html PATH --json
+            --fail-on-high / --fail-on-medium
+        U
+        "findings" => <<~U,
+          Usage: heapscope findings REPORT.json [options]
+            --severity LEVEL       Filter: low|medium|high
+            --code HS001             Filter by diagnostic code
+            --json                   Machine-readable output
+        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,
+          Usage: heapscope pack REPORT.json [options]
+            -o, --output DIR         Output directory
+            --label NAME             File basename
+        U
+        "export" => "Alias of pack. See: heapscope help pack\n",
+        "suggest" => <<~U,
+          Usage: heapscope suggest REPORT.json [options]
+            --json                   next_steps + ignore_patterns
+            --ignores-only           Print ignore patterns only
+        U
+        "ignore-suggest" => "Alias of suggest. See: heapscope help suggest\n",
+        "report" => <<~U,
+          Usage: heapscope report REPORT.json [options]
+            --format FMT             text|html|json|markdown|md
+            -o, --output PATH
+        U
+        "baseline" => "Usage: heapscope baseline create REPORT.json -o baseline.json\n",
+        "compare" => <<~U,
+          Usage: heapscope compare BASELINE.json CURRENT.json [options]
+            --threshold F            Relative growth threshold (default 0.5)
+            --json                   Machine-readable result
+        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
+    end
+  end
+end

data/lib/heapscope/cli/support.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module HeapScope
+  class CLI
+    # Shared helpers for option parsing, output, and severity exits.
+    module Support
+      SEVERITY_RANK = { low: 1, medium: 2, high: 3 }.freeze
+
+      private
+
+      def color?
+        @color_enabled
+      end
+
+      def json_mode?
+        @json_mode
+      end
+
+      def quiet?
+        HeapScope.config.quiet
+      end
+
+      def say(msg = "")
+        return if quiet?
+
+        puts msg
+      end
+
+      def say_err(msg)
+        warn msg
+      end
+
+      def emit_json(payload)
+        puts JSON.pretty_generate(payload)
+      end
+
+      def colorize(text, code)
+        Color.wrap(text, code, enabled: color?)
+      end
+
+      def load_report!(path)
+        raise ArgumentError, "report path required" if path.nil? || path.empty?
+        raise InvalidReportError, "File not found: #{path}" unless File.exist?(path)
+
+        Report.load(path)
+      end
+
+      def load_json_path!(path)
+        raise ArgumentError, "path required" if path.nil? || path.empty?
+        raise InvalidReportError, "File not found: #{path}" unless File.exist?(path)
+
+        JSON.parse(File.read(path), symbolize_names: true)
+      end
+
+      def parse_fail_on!(options, opts)
+        opts.on("--fail-on-high", "Exit 1 if HIGH findings present") { options[:fail_on] = :high }
+        opts.on("--fail-on-medium", "Exit 1 if MEDIUM or HIGH findings present") { options[:fail_on] = :medium }
+        opts.on("--fail-on LEVEL", %w[low medium high], "Exit 1 if findings at/above LEVEL") do |level|
+          options[:fail_on] = level.to_sym
+        end
+      end
+
+      def exit_for_findings(report, fail_on: nil)
+        return EXIT_OK unless fail_on
+
+        threshold = SEVERITY_RANK[fail_on.to_sym]
+        raise ArgumentError, "invalid fail-on level: #{fail_on}" unless threshold
+
+        if report.findings.any? { |f| SEVERITY_RANK.fetch(f.severity.to_sym, 0) >= threshold }
+          EXIT_REGRESSION
+        else
+          EXIT_OK
+        end
+      end
+
+      def print_report_views(report, options)
+        if json_mode? || options[:json]
+          emit_json(report.to_h)
+          return
+        end
+
+        if options[:scorecard_only]
+          say report.scorecard(title: options[:title] || "HeapScope").to_text
+          return
+        end
+
+        return if quiet?
+
+        say report.scorecard(title: options[:title] || "HeapScope").to_text unless options[:no_scorecard]
+        if options[:table] != false && report.diff
+          say
+          say report.table(format: options[:markdown] ? :markdown : :ascii)
+        end
+        say
+        if options[:markdown]
+          puts report.to_markdown
+        else
+          puts report.to_text
+        end
+      end
+
+      def write_outputs(report, options)
+        report.save(options[:output]) if options[:output]
+        report.save_html(options[:html]) if options[:html]
+        report.save_markdown(options[:markdown_out]) if options[:markdown_out]
+      end
+
+      def run_file_or_eval!(options)
+        if options[:file]
+          raise ArgumentError, "File not found: #{options[:file]}" unless File.exist?(options[:file])
+
+          load(options[:file])
+        elsif options[:eval]
+          # Intentional: CLI probe/measure of user-provided snippet in local process only.
+          eval(options[:eval], TOPLEVEL_BINDING, "(heapscope-eval)") # rubocop:disable Security/Eval
+        else
+          raise ArgumentError, "provide --file PATH or --eval 'ruby'"
+        end
+      end
+
+      def command_wants_help?(argv)
+        argv.any? { |a| a == "-h" || a == "--help" }
+      end
+    end
+  end
+end

data/lib/heapscope/cli.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+require "fileutils"
+
+require_relative "cli/color"
+require_relative "cli/support"
+require_relative "cli/help"
+require_relative "cli/completion"
+require_relative "cli/commands/capture"
+require_relative "cli/commands/diffing"
+require_relative "cli/commands/reporting"
+require_relative "cli/commands/meta"
+
+module HeapScope
+  # Polished, expansive CLI for HeapScope diagnostics (local-only).
+  class CLI
+    include Support
+    include Commands::Capture
+    include Commands::Diffing
+    include Commands::Reporting
+    include Commands::Meta
+
+    EXIT_OK = 0
+    EXIT_REGRESSION = 1
+    EXIT_INVALID = 2
+    EXIT_CAPABILITY = 3
+
+    COMMAND_MAP = {
+      "snapshot" => :cmd_snapshot,
+      "inspect" => :cmd_inspect,
+      "diff" => :cmd_diff,
+      "monitor" => :cmd_monitor,
+      "watch" => :cmd_watch,
+      "trends" => :cmd_trends,
+      "report" => :cmd_report,
+      "compare" => :cmd_compare,
+      "baseline" => :cmd_baseline,
+      "sessions" => :cmd_sessions,
+      "history" => :cmd_history,
+      "validate" => :cmd_validate,
+      "suggest" => :cmd_suggest,
+      "ignore-suggest" => :cmd_ignore_suggest,
+      "pack" => :cmd_pack,
+      "export" => :cmd_export,
+      "probe" => :cmd_probe,
+      "measure" => :cmd_measure,
+      "retention" => :cmd_retention,
+      "findings" => :cmd_findings,
+      "scorecard" => :cmd_scorecard,
+      "table" => :cmd_table,
+      "explain" => :cmd_explain,
+      "open" => :cmd_open,
+      "html" => :cmd_html,
+      "self-test" => :cmd_self_test,
+      "env" => :cmd_env,
+      "completion" => :cmd_completion,
+      "man" => :cmd_man,
+      "codes" => :cmd_codes,
+      "doctor" => :cmd_doctor,
+      "overhead" => :cmd_overhead,
+      "config" => :cmd_config,
+      "about" => :cmd_about,
+      "capabilities" => :cmd_capabilities
+    }.freeze
+
+    def self.run(argv = ARGV)
+      new.run(argv)
+    end
+
+    def initialize
+      @json_mode = false
+      @color_enabled = Color.enabled?
+    end
+
+    def run(argv)
+      argv = argv.map(&:to_s)
+      parse_globals!(argv)
+
+      command = argv.shift
+      case command
+      when "version", "-v", "--version"
+        puts "heapscope #{VERSION}"
+        EXIT_OK
+      when "help", "-h", "--help", nil
+        topic = argv.shift
+        if topic && Help::COMMANDS.key?(topic)
+          puts Help.command_help(topic)
+          EXIT_OK
+        else
+          print_help
+          command.nil? ? EXIT_INVALID : EXIT_OK
+        end
+      else
+        method = COMMAND_MAP[command]
+        unless method
+          say_err Color.err("Unknown command: #{command}", enabled: color?)
+          print_help
+          return EXIT_INVALID
+        end
+        send(method, argv)
+      end
+    rescue CapabilityError => e
+      say_err "Capability unavailable: #{e.message}"
+      EXIT_CAPABILITY
+    rescue InvalidReportError, SnapshotError, ConfigurationError, ArgumentError => e
+      say_err "Invalid input: #{e.message}"
+      EXIT_INVALID
+    rescue BudgetExceededError => e
+      say_err e.message
+      EXIT_REGRESSION
+    end
+
+    private
+
+    def parse_globals!(argv)
+      loop do
+        break if argv.empty?
+
+        case argv.first
+        when "--verbose"
+          argv.shift
+          HeapScope.config.verbose = true
+        when "--quiet"
+          argv.shift
+          HeapScope.config.quiet = true
+        when "--json"
+          argv.shift
+          @json_mode = true
+        when "--no-color"
+          argv.shift
+          @color_enabled = false
+        when "--color"
+          argv.shift
+          @color_enabled = true
+        when "--config"
+          argv.shift
+          path = argv.shift or raise ArgumentError, "--config requires PATH"
+          HeapScope.load_config!(path)
+        when /\A--config=(.+)\z/
+          argv.shift
+          HeapScope.load_config!(::Regexp.last_match(1))
+        else
+          break
+        end
+      end
+    end
+
+    def print_help
+      puts Help.global_help
+    end
+
+    def help_exit(command)
+      text = Help.command_help(command)
+      if text
+        puts text
+        EXIT_OK
+      else
+        print_help
+        EXIT_INVALID
+      end
+    end
+  end
+end

data/lib/heapscope/closures.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module HeapScope
+  # Conservative Proc/closure retention analysis.
+  # Ruby does not expose captured bindings cleanly — treat results as hypotheses.
+  module Closures
+    module_function
+
+    def inventory(limit: 200)
+      procs = []
+      return procs unless Runtime.current.each_object?
+
+      Runtime.current.each_object(Proc) do |proc|
+        break if procs.size >= limit
+
+        info = Runtime.current.allocation_info(proc)
+        retained = begin
+          Graph.new.estimate_retained_size(proc, max_objects: 500, max_depth: 4)
+        rescue StandardError
+          { retained: nil }
+        end
+        procs << {
+          class: "Proc",
+          lambda: proc.lambda?,
+          arity: begin
+            proc.arity
+          rescue StandardError
+            nil
+          end,
+          allocation: info,
+          shallow_bytes: Runtime.current.memsize_of(proc),
+          approx_retained: retained[:retained],
+          approximate: true,
+          note: "Closure captures are not fully introspectable — retained size is approximate."
+        }
+      end
+      procs
+    rescue StandardError
+      []
+    end
+
+    def findings(procs)
+      procs.select { |p| p[:approx_retained].to_i > 500_000 }.map do |p|
+        site = p.dig(:allocation, :file) && "#{p[:allocation][:file]}:#{p[:allocation][:line]}"
+        Finding.new(
+          code: "HS006",
+          severity: :medium,
+          subject: site || "Proc",
+          facts: [
+            "Observed fact: Proc approx retained #{p[:approx_retained]} bytes" \
+            "#{site ? " allocated at #{site}" : ""}."
+          ],
+          derived: ["Derived: bounded retained-size estimate exceeded 500KB."],
+          hypothesis: "A long-lived Proc may be capturing a large object graph.",
+          suspected_cause: site,
+          suggestions: [
+            "Avoid capturing large objects in long-lived callbacks",
+            "Prefer weak refs or explicit clearable context objects"
+          ],
+          evidence: [p]
+        )
+      end
+    end
+  end
+
+  # Fiber / execution-context awareness (best-effort).
+  module Fibers
+    module_function
+
+    def inventory
+      list = []
+      if defined?(Fiber) && Fiber.respond_to?(:list)
+        Fiber.list.each do |fiber|
+          list << fiber_info(fiber)
+        end
+      elsif defined?(Fiber)
+        list << fiber_info(Fiber.current)
+      end
+      list
+    rescue StandardError => e
+      [{ error: e.message }]
+    end
+
+    def fiber_info(fiber)
+      storage =
+        if fiber.respond_to?(:storage)
+          fiber.storage
+        else
+          {}
+        end
+      {
+        object_id: fiber.__id__,
+        alive: (fiber.alive? if fiber.respond_to?(:alive?)),
+        storage_keys: storage.respond_to?(:keys) ? storage.keys.map(&:inspect) : [],
+        storage_size: storage.respond_to?(:size) ? storage.size : nil,
+        note: "Fiber-local storage support varies by Ruby version."
+      }
+    rescue StandardError => e
+      { error: e.message }
+    end
+  end
+end