hone 0.1.0

data/lib/hone/analyzer.rb

@@ -0,0 +1,258 @@
+# frozen_string_literal: true
+
+module Hone
+  # Orchestrates the full analysis pipeline:
+  # Scanner -> MethodMap -> Profiler -> Correlator -> Reporter
+  #
+  # @example Basic usage (static analysis only)
+  #   analyzer = Hone::Analyzer.new("app.rb")
+  #   result = analyzer.run
+  #   puts result.output
+  #
+  # @example With profile correlation
+  #   analyzer = Hone::Analyzer.new("app.rb", profile: "profile.json")
+  #   result = analyzer.run
+  #
+  # @example Directory analysis
+  #   analyzer = Hone::Analyzer.new("lib/", format: :json)
+  #   result = analyzer.run
+  #
+  class Analyzer
+    # Default directory for cached profile files
+    PROFILE_DIR = "tmp/hone"
+
+    # Result of analysis containing findings, output, and exit code
+    Result = Data.define(:findings, :output, :exit_code)
+
+    # @param path [String] File or directory to analyze
+    # @param profile [String, nil] Path to StackProf JSON profile
+    # @param memory_profile [String, nil] Path to MemoryProfiler JSON profile
+    # @param format [Symbol] Output format: :text, :json, :github
+    # @param color [Boolean, nil] Force color output (nil = auto-detect)
+    # @param quiet [Boolean] Minimal output
+    # @param verbose [Boolean] Extended output with pattern details
+    # @param top [Integer, nil] Show only top N findings
+    # @param hot_only [Boolean] Only show HOT findings
+    # @param show_cold [Boolean] Include COLD findings
+    # @param fail_on [Symbol] Exit non-zero for: :hot, :warm, :any, :none
+    # @param diff [String, nil] Git ref to compare against for changed files
+    # @param baseline [String, nil] Path to baseline JSON file to suppress findings
+    # @param rails [Boolean] Enable Rails-specific analysis
+    def initialize(path, profile: nil, memory_profile: nil, format: :text, color: nil, quiet: false, verbose: false,
+      top: nil, hot_only: false, show_cold: false, fail_on: :hot, diff: nil, baseline: nil, rails: false)
+      @path = path
+      @profile_path = profile || auto_detect_profile(:cpu)
+      @memory_profile_path = memory_profile || auto_detect_profile(:memory)
+      @format = format.to_sym
+      @color = color
+      @quiet = quiet
+      @verbose = verbose
+      @top = top
+      @hot_only = hot_only
+      @show_cold = show_cold
+      @fail_on = fail_on.to_sym
+      @diff = diff
+      @baseline = baseline
+      @rails = rails
+    end
+
+    # Run the analysis pipeline
+    # @return [Result] Analysis result with findings, output, and exit code
+    def run
+      validate_input!
+
+      # Step 1: Scan for patterns
+      findings = scan_path
+
+      # Step 2: Build method map for correlation
+      method_map = build_method_map
+
+      # Step 3: Load profile data (if available)
+      profiles = load_profiles
+
+      # Step 4: Correlate findings with profile
+      correlator = Correlator.new(
+        method_map: method_map,
+        cpu_profile: profiles[:cpu],
+        memory_profile: profiles[:memory]
+      )
+      correlated = correlator.correlate(findings)
+
+      # Step 5: Apply filtering
+      filtered = apply_filters(correlated)
+
+      # Step 6: Generate output
+      output = generate_output(filtered)
+
+      # Step 7: Calculate exit code
+      exit_code = calculate_exit_code(filtered)
+
+      Result.new(findings: filtered, output: output, exit_code: exit_code)
+    rescue Error => e
+      Result.new(findings: [], output: "Error: #{e.message}", exit_code: ExitCodes::ERROR)
+    rescue => e
+      Result.new(findings: [], output: "Error: #{e.message}\n#{e.backtrace.first(5).join("\n")}", exit_code: ExitCodes::ERROR)
+    end
+
+    private
+
+    def validate_input!
+      raise Error, "Path not found: #{@path}" unless File.exist?(@path)
+
+      raise Error, "Profile not found: #{@profile_path}" if @profile_path && !File.exist?(@profile_path)
+
+      raise Error, "Baseline not found: #{@baseline}" if @baseline && !File.exist?(@baseline)
+
+      raise Error, "Memory profile not found: #{@memory_profile_path}" if @memory_profile_path && !File.exist?(@memory_profile_path)
+
+      unless %i[text json github sarif junit tsv].include?(@format)
+        raise Error, "Invalid format: #{@format}. Use text, json, github, sarif, junit, or tsv."
+      end
+
+      return if %i[hot warm any none].include?(@fail_on)
+
+      raise Error, "Invalid fail_on: #{@fail_on}. Use hot, warm, any, or none."
+    end
+
+    def scan_path
+      scanner = Scanner.new(rails: @rails)
+
+      if File.directory?(@path)
+        scanner.scan_directory(@path)
+      else
+        scanner.scan_file(@path)
+      end
+    end
+
+    def build_method_map
+      method_map = MethodMap.new
+
+      if File.directory?(@path)
+        Dir.glob(File.join(@path, "**/*.rb")).each do |file|
+          method_map.add_file(file)
+        end
+      else
+        method_map.add_file(@path)
+      end
+
+      method_map
+    end
+
+    def load_profiles
+      {
+        cpu: load_cpu_profile,
+        memory: load_memory_profile
+      }
+    end
+
+    def load_cpu_profile
+      Profilers::Factory.create(@profile_path)
+    end
+
+    def load_memory_profile
+      return nil unless @memory_profile_path
+
+      Profilers::MemoryProfiler.new(@memory_profile_path)
+    end
+
+    def apply_filters(findings)
+      FindingFilter.new(findings, filter_options).apply
+    end
+
+    def filter_options
+      {
+        diff: @diff,
+        baseline: @baseline,
+        hot_only: @hot_only,
+        show_cold: @show_cold,
+        profile_path: @profile_path,
+        top: @top
+      }
+    end
+
+    def generate_output(findings)
+      case @format
+      when :json
+        Formatters::JSON.new(findings, reporter_options).format
+      when :github
+        Formatters::GitHub.new(findings, reporter_options).format
+      when :sarif
+        Formatters::SARIF.new(findings, reporter_options).format
+      when :junit
+        Formatters::JUnit.new(findings, reporter_options).format
+      when :tsv
+        Formatters::TSV.new(findings, reporter_options).format
+      else
+        Reporter.new(findings, reporter_options).report
+      end
+    end
+
+    def reporter_options
+      {
+        show_cold: @show_cold,
+        quiet: @quiet,
+        verbose: @verbose,
+        color: determine_color,
+        profile_path: @profile_path,
+        memory_profile_path: @memory_profile_path,
+        file_path: @path,
+        mode: @profile_path ? "correlated" : "static"
+      }
+    end
+
+    def determine_color
+      return @color unless @color.nil?
+
+      # Auto-detect: color if TTY and NO_COLOR not set
+      $stdout.tty? && !ENV["NO_COLOR"]
+    end
+
+    def calculate_exit_code(findings)
+      return ExitCodes::SUCCESS if findings.empty?
+
+      case @fail_on
+      when :none
+        ExitCodes::SUCCESS
+      when :any
+        ExitCodes::HOT
+      when :hot
+        has_hot = findings.any? { |f| f.priority == :hot }
+        has_hot ? ExitCodes::HOT : ExitCodes::SUCCESS
+      when :warm
+        has_hot = findings.any? { |f| f.priority == :hot }
+        has_warm = findings.any? { |f| f.priority == :warm }
+
+        if has_hot
+          ExitCodes::HOT
+        elsif has_warm
+          ExitCodes::WARM
+        else
+          ExitCodes::SUCCESS
+        end
+      else
+        ExitCodes::SUCCESS
+      end
+    end
+
+    def auto_detect_profile(type)
+      filename = case type
+      when :cpu then "cpu_profile.json"
+      when :memory then "memory_profile.json"
+      end
+
+      path = File.join(PROFILE_DIR, filename)
+
+      if File.exist?(path)
+        metadata_path = File.join(PROFILE_DIR, "metadata.json")
+        if File.exist?(metadata_path)
+          metadata = JSON.parse(File.read(metadata_path))
+          generated = metadata["generated_at"]
+          warn "Using cached #{type} profile from #{path} (generated: #{generated})"
+        else
+          warn "Using cached #{type} profile from #{path}"
+        end
+        path
+      end
+    end
+  end
+end

data/lib/hone/cli.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+require "thor"
+require_relative "harness"
+require_relative "harness_generator"
+require_relative "harness_runner"
+
+module Hone
+  # Command-line interface for Hone Ruby performance analyzer.
+  #
+  # @example Basic usage
+  #   hone analyze FILE                    # Static analysis (no profile)
+  #   hone analyze FILE --profile FILE     # Correlation mode (prioritized)
+  #   hone analyze DIR                     # Analyze directory
+  #
+  # @example Output control
+  #   hone analyze FILE --format json      # JSON output
+  #   hone analyze FILE --format github    # GitHub Actions annotations
+  #   hone analyze FILE --quiet            # Minimal output
+  #   hone analyze FILE --no-color         # Disable colors
+  #
+  # @example Filtering
+  #   hone analyze FILE --top=10           # Show only top 10 findings
+  #   hone analyze FILE --hot-only         # Only HOT findings
+  #   hone analyze FILE --show-cold        # Include COLD findings
+  #
+  # @example CI integration
+  #   hone analyze FILE --fail-on hot      # Exit 1 for HOT (default)
+  #   hone analyze FILE --fail-on warm     # Exit 2 for WARM, 1 for HOT
+  #   hone analyze FILE --fail-on any      # Exit 1 for any finding
+  #   hone analyze FILE --fail-on none     # Always exit 0
+  #
+  class CLI < Thor
+    def self.exit_on_failure?
+      true
+    end
+
+    desc "version", "Print version"
+    def version
+      puts "Hone v#{Hone::VERSION}"
+    end
+    map %w[-v --version] => :version
+
+    desc "analyze PATH", "Analyze Ruby file(s) for optimization opportunities"
+    long_desc <<~DESC
+      Analyze Ruby source files for performance optimization opportunities.
+
+      When run with --profile, findings are correlated with runtime profiling data
+      to prioritize optimizations that will have the greatest impact. Findings are
+      categorized as HOT (>5% CPU), WARM (1-5% CPU), or COLD (<1% CPU).
+
+      Without --profile, all findings are reported without prioritization.
+
+      Exit codes:
+        0 - No findings, or only COLD findings
+        1 - HOT findings exist
+        2 - WARM findings exist (no HOT)
+        3 - Error occurred
+
+      Examples:
+        hone analyze app.rb
+        hone analyze lib/ --profile profile.json
+        hone analyze . --format github --fail-on warm
+    DESC
+    option :profile,
+      type: :string,
+      desc: "StackProf JSON profile for correlation",
+      aliases: "-p"
+    option :memory_profile,
+      type: :string,
+      desc: "MemoryProfiler JSON for allocation correlation",
+      aliases: "-m"
+    option :format,
+      type: :string,
+      default: "text",
+      desc: "Output format: text, json, github, sarif, junit, tsv",
+      aliases: "-f"
+    option :color,
+      type: :boolean,
+      default: nil,
+      desc: "Force color output (default: auto-detect TTY)"
+    option :quiet,
+      type: :boolean,
+      default: false,
+      desc: "Minimal output (one line per finding)",
+      aliases: "-q"
+    option :verbose,
+      type: :boolean,
+      default: false,
+      desc: "Extended output with pattern details",
+      aliases: "-V"
+    option :top,
+      type: :numeric,
+      desc: "Show only top N findings"
+    option :hot_only,
+      type: :boolean,
+      default: false,
+      desc: "Only show HOT findings"
+    option :show_cold,
+      type: :boolean,
+      default: false,
+      desc: "Include COLD findings in output"
+    option :fail_on,
+      type: :string,
+      default: "hot",
+      desc: "Exit non-zero for: hot (default), warm, any, none"
+    option :diff,
+      type: :string,
+      desc: "Only analyze files changed since BASE ref"
+    option :baseline,
+      type: :string,
+      desc: "Suppress findings in baseline JSON file"
+    option :rails,
+      type: :boolean,
+      default: false,
+      desc: "Include Rails/ActiveSupport-specific optimizations"
+    def analyze(path)
+      analyzer = Analyzer.new(
+        path,
+        profile: options[:profile],
+        memory_profile: options[:memory_profile],
+        format: options[:format],
+        color: options[:color],
+        quiet: options[:quiet],
+        verbose: options[:verbose],
+        top: options[:top],
+        hot_only: options[:hot_only],
+        show_cold: options[:show_cold],
+        fail_on: options[:fail_on],
+        diff: options[:diff],
+        baseline: options[:baseline],
+        rails: options[:rails]
+      )
+
+      result = analyzer.run
+
+      puts result.output unless result.output.empty?
+
+      exit result.exit_code
+    end
+
+    desc "init COMPONENT", "Initialize Hone components"
+    long_desc <<~DESC
+      Initialize Hone components in your project.
+
+      Components:
+        harness - Generate a performance harness template
+
+      Examples:
+        hone init harness        # Generate basic Ruby harness
+        hone init harness --rails  # Generate Rails-specific harness
+    DESC
+    option :rails,
+      type: :boolean,
+      default: false,
+      desc: "Generate Rails-specific harness template"
+    def init(component)
+      case component
+      when "harness"
+        generator = HarnessGenerator.new(rails: options[:rails])
+        generator.generate
+      else
+        puts "Unknown component: #{component}"
+        puts "Available components: harness"
+        exit 1
+      end
+    end
+
+    desc "profile", "Run harness and generate performance profiles"
+    long_desc <<~DESC
+      Run the performance harness and generate CPU (and optionally memory) profiles.
+
+      The harness file should define setup, exercise, and teardown blocks.
+      Profiles are saved to tmp/hone/ by default.
+
+      Examples:
+        hone profile                    # Run default harness
+        hone profile --memory           # Include memory profiling
+        hone profile --analyze          # Profile then analyze
+        hone profile --harness custom.rb  # Use custom harness file
+    DESC
+    option :harness,
+      type: :string,
+      default: ".hone/harness.rb",
+      desc: "Path to harness file"
+    option :profiler,
+      type: :string,
+      enum: %w[auto stackprof vernier],
+      default: "auto",
+      desc: "CPU profiler to use"
+    option :memory,
+      type: :boolean,
+      default: false,
+      desc: "Include memory profiling"
+    option :warmup,
+      type: :numeric,
+      default: 10,
+      desc: "Warmup iterations before profiling"
+    option :output,
+      type: :string,
+      default: "tmp/hone",
+      desc: "Output directory for profiles"
+    option :analyze,
+      type: :boolean,
+      default: false,
+      desc: "Run analysis after profiling"
+    def profile
+      unless File.exist?(options[:harness])
+        puts "Harness file not found: #{options[:harness]}"
+        puts "Run 'hone init harness' to generate a template."
+        exit 1
+      end
+
+      profiler_opt = (options[:profiler] == "auto") ? nil : options[:profiler].to_sym
+
+      runner = HarnessRunner.new(
+        options[:harness],
+        profiler: profiler_opt,
+        memory: options[:memory],
+        warmup: options[:warmup],
+        output_dir: options[:output]
+      )
+
+      puts "Loading harness from #{options[:harness]}..."
+      puts "Warmup: #{options[:warmup]} iterations"
+      puts "Profiler: #{profiler_opt || "auto-detect"}"
+      puts
+
+      profiles = runner.run
+
+      puts "Profiles generated:"
+      puts "  CPU:    #{profiles[:cpu]}"
+      puts "  Memory: #{profiles[:memory]}" if profiles[:memory]
+      puts
+
+      if options[:analyze]
+        puts "Running analysis..."
+        invoke :analyze, ["."], profile: profiles[:cpu], memory_profile: profiles[:memory]
+      else
+        puts "Run analysis with:"
+        puts "  hone analyze . --profile #{profiles[:cpu]}"
+      end
+    end
+
+    default_task :analyze
+  end
+end

data/lib/hone/config.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Hone
+  class Config
+    CONFIG_FILE = ".hone/config.yml"
+
+    DEFAULTS = {
+      harness: {
+        warmup_iterations: 10,
+        profile_iterations: 100,
+        path: ".hone/harness.rb"
+      },
+      profilers: {
+        cpu: "auto",
+        memory: false
+      },
+      output: {
+        dir: "tmp/hone"
+      },
+      analysis: {
+        rails: false,
+        show_cold: false,
+        top: nil
+      }
+    }.freeze
+
+    def initialize(path = CONFIG_FILE)
+      @path = path
+      @data = load_config
+    end
+
+    def harness
+      @data[:harness]
+    end
+
+    def profilers
+      @data[:profilers]
+    end
+
+    def output
+      @data[:output]
+    end
+
+    def analysis
+      @data[:analysis]
+    end
+
+    def [](key)
+      @data[key.to_sym]
+    end
+
+    def exist?
+      File.exist?(@path)
+    end
+
+    private
+
+    def load_config
+      return deep_symbolize(DEFAULTS.dup) unless File.exist?(@path)
+
+      user_config = YAML.safe_load_file(@path, symbolize_names: true) || {}
+      deep_merge(DEFAULTS, user_config)
+    rescue Psych::SyntaxError => e
+      warn "Warning: Invalid config file #{@path}: #{e.message}"
+      deep_symbolize(DEFAULTS.dup)
+    end
+
+    def deep_merge(base, override)
+      result = {}
+      base.each do |key, value|
+        result[key] = if value.is_a?(Hash) && override[key].is_a?(Hash)
+          deep_merge(value, override[key])
+        elsif override.key?(key)
+          override[key]
+        else
+          value
+        end
+      end
+      override.each do |key, value|
+        result[key] = value unless result.key?(key)
+      end
+      result
+    end
+
+    def deep_symbolize(hash)
+      hash.transform_keys(&:to_sym).transform_values do |v|
+        v.is_a?(Hash) ? deep_symbolize(v) : v
+      end
+    end
+  end
+end