hone 0.1.0

data/lib/hone/harness_runner.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+
+module Hone
+  class HarnessRunner
+    PROFILE_DIR = "tmp/hone"
+
+    attr_reader :harness_path, :profiler, :include_memory, :warmup, :output_dir
+
+    def initialize(harness_path, options = {})
+      @harness_path = harness_path
+      @profiler = options[:profiler] || detect_profiler
+      @include_memory = options.fetch(:memory, false)
+      @warmup = options.fetch(:warmup, 10)
+      @output_dir = options.fetch(:output_dir, PROFILE_DIR)
+    end
+
+    def run
+      harness = Harness.load(@harness_path)
+
+      unless harness.valid?
+        raise Hone::Error, "Harness must define an exercise block"
+      end
+
+      FileUtils.mkdir_p(@output_dir)
+
+      # Setup phase (not profiled)
+      harness.run_setup
+
+      # Warmup phase (not profiled, lets JIT optimize)
+      @warmup.times { harness.run_exercise }
+
+      # Profile CPU
+      cpu_path = profile_cpu(harness)
+
+      # Profile memory (if requested)
+      memory_path = @include_memory ? profile_memory(harness) : nil
+
+      # Teardown phase
+      harness.run_teardown
+
+      # Write metadata
+      write_metadata(cpu_path, memory_path, harness.iterations)
+
+      {cpu: cpu_path, memory: memory_path}
+    end
+
+    private
+
+    def profile_cpu(harness)
+      path = File.join(@output_dir, "cpu_profile.json")
+
+      case @profiler
+      when :stackprof
+        profile_with_stackprof(harness, path)
+      when :vernier
+        profile_with_vernier(harness, path)
+      else
+        raise Hone::Error, "Unknown profiler: #{@profiler}"
+      end
+
+      path
+    end
+
+    def profile_with_stackprof(harness, path)
+      require "stackprof"
+      # Run profiling and capture the result (don't let StackProf write Marshal format)
+      # ignore_gc: true - skip GC frames (not actionable)
+      result = StackProf.run(mode: :cpu, raw: true, interval: 1000, ignore_gc: true) do
+        harness.iterations.times { harness.run_exercise }
+      end
+      # Convert to JSON format that Hone can parse, filtering C frames
+      File.write(path, stackprof_to_json(result))
+    end
+
+    def stackprof_to_json(data)
+      # Convert StackProf result to JSON with string keys
+      # Filter out C frames (file is nil or contains <cfunc>) and recalculate
+      ruby_frames = {}
+      ruby_samples = 0
+
+      data[:frames].each do |address, frame|
+        file = frame[:file]
+        # Skip C functions and internal frames
+        next if file.nil? || file.empty? || file.include?("<cfunc>") || file.start_with?("(")
+
+        samples = frame[:samples] || 0
+        ruby_samples += samples
+
+        ruby_frames[address.to_s] = {
+          "name" => frame[:name],
+          "file" => file,
+          "line" => frame[:line],
+          "samples" => samples,
+          "total_samples" => frame[:total_samples] || 0
+        }
+      end
+
+      {
+        "mode" => data[:mode].to_s,
+        "samples" => data[:samples],
+        "ruby_samples" => ruby_samples,
+        "frames" => ruby_frames
+      }.then { |json_data| JSON.pretty_generate(json_data) }
+    end
+
+    def profile_with_vernier(harness, path)
+      require "vernier"
+      Vernier.profile(out: path) do
+        harness.iterations.times { harness.run_exercise }
+      end
+    end
+
+    def profile_memory(harness)
+      path = File.join(@output_dir, "memory_profile.json")
+      require "memory_profiler"
+
+      report = MemoryProfiler.report do
+        harness.run_exercise
+      end
+
+      File.write(path, memory_report_to_json(report))
+      path
+    end
+
+    def memory_report_to_json(report)
+      # Convert MemoryProfiler report to JSON format
+      data = {
+        total_allocated: report.total_allocated,
+        total_retained: report.total_retained,
+        allocated_memory_by_location: report.allocated_memory_by_location.map do |stat|
+          {location: stat[:data], bytes: stat[:count]}
+        end,
+        retained_memory_by_location: report.retained_memory_by_location.map do |stat|
+          {location: stat[:data], bytes: stat[:count]}
+        end
+      }
+      JSON.pretty_generate(data)
+    end
+
+    def write_metadata(cpu_path, memory_path, iterations)
+      metadata = {
+        generated_at: Time.now.iso8601,
+        ruby_version: RUBY_VERSION,
+        yjit_enabled: defined?(RubyVM::YJIT) && RubyVM::YJIT.enabled?,
+        profiler: @profiler.to_s,
+        warmup_iterations: @warmup,
+        profile_iterations: iterations,
+        cpu_profile: cpu_path,
+        memory_profile: memory_path
+      }
+
+      File.write(File.join(@output_dir, "metadata.json"), JSON.pretty_generate(metadata))
+    end
+
+    def detect_profiler
+      # Prefer Vernier if available (modern, better output)
+
+      require "vernier"
+      :vernier
+    rescue LoadError
+      begin
+        require "stackprof"
+        :stackprof
+      rescue LoadError
+        raise Hone::Error, "No profiler available. Install stackprof or vernier gem."
+      end
+    end
+  end
+end

data/lib/hone/method_map.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Hone
+  # Maps method definitions to their line ranges for correlating hotspots
+  # with specific methods in Ruby source files.
+  class MethodMap
+    MethodInfo = Data.define(:name, :class_name, :file, :start_line, :end_line) do
+      def contains_line?(line)
+        (start_line..end_line).cover?(line)
+      end
+
+      def qualified_name
+        class_name ? "#{class_name}##{name}" : name
+      end
+    end
+
+    def initialize
+      @methods = []
+    end
+
+    # Parse a Ruby file and extract all method definitions
+    def add_file(path)
+      normalized_path = File.expand_path(path)
+      result = Prism.parse_file(normalized_path)
+
+      if result.errors.any?
+        warn "Parse errors in #{normalized_path}:"
+        result.errors.each { |e| warn "  #{e.message}" }
+        return self
+      end
+
+      extractor = MethodExtractor.new(normalized_path)
+      result.value.accept(extractor)
+      @methods.concat(extractor.methods)
+
+      self
+    end
+
+    # Find the method that contains a given line in a file
+    def method_at(file, line)
+      normalized_file = File.expand_path(file)
+
+      @methods.find do |method|
+        method.file == normalized_file && method.contains_line?(line)
+      end
+    end
+
+    # Return all methods for a given file
+    def methods_in_file(file)
+      normalized_file = File.expand_path(file)
+
+      @methods.select do |method|
+        method.file == normalized_file
+      end
+    end
+
+    # Return all registered methods
+    def all_methods
+      @methods.dup
+    end
+
+    # Internal visitor for extracting methods from Prism AST
+    class MethodExtractor < Prism::Visitor
+      attr_reader :methods
+
+      def initialize(file_path)
+        @file_path = file_path
+        @methods = []
+        @context_stack = []
+        super()
+      end
+
+      def visit_class_node(node)
+        class_name = extract_constant_name(node.constant_path)
+        @context_stack.push(class_name)
+        super
+        @context_stack.pop
+      end
+
+      def visit_module_node(node)
+        module_name = extract_constant_name(node.constant_path)
+        @context_stack.push(module_name)
+        super
+        @context_stack.pop
+      end
+
+      def visit_def_node(node)
+        method_name = node.name.to_s
+        class_name = @context_stack.any? ? @context_stack.join("::") : nil
+
+        @methods << MethodInfo.new(
+          name: method_name,
+          class_name: class_name,
+          file: @file_path,
+          start_line: node.location.start_line,
+          end_line: node.location.end_line
+        )
+
+        super
+      end
+
+      def visit_singleton_method_node(node)
+        method_name = "self.#{node.name}"
+        class_name = @context_stack.any? ? @context_stack.join("::") : nil
+
+        @methods << MethodInfo.new(
+          name: method_name,
+          class_name: class_name,
+          file: @file_path,
+          start_line: node.location.start_line,
+          end_line: node.location.end_line
+        )
+
+        super
+      end
+
+      private
+
+      def extract_constant_name(node)
+        case node
+        when Prism::ConstantReadNode
+          node.name.to_s
+        when Prism::ConstantPathNode
+          parts = []
+          current = node
+          while current.is_a?(Prism::ConstantPathNode)
+            parts.unshift(current.name.to_s)
+            current = current.parent
+          end
+          parts.unshift(current.name.to_s) if current.is_a?(Prism::ConstantReadNode)
+          parts.join("::")
+        else
+          node.to_s
+        end
+      end
+    end
+  end
+end

data/lib/hone/patterns/README.md

@@ -0,0 +1,174 @@
+# Hone Pattern Detection Approaches
+
+This document describes the different approaches used for detecting optimization patterns in Ruby code.
+
+## Overview
+
+Hone uses Prism AST visitors to detect code patterns that could be optimized. Patterns range from simple single-node checks to complex data flow analysis.
+
+## Pattern Tiers
+
+| Tier | Complexity | Example |
+|------|------------|---------|
+| 1: Simple AST | Single node inspection | `.positive?` → `> 0` |
+| 2: Context-Aware | Track loop/method scope | String concat in loop |
+| 3: Scope-Limited | Track variables within scope | `chars = str.chars; chars[0]` |
+| 4: Taint Tracking | Track data flow across assignments | Aliased variable detection |
+
+## Approach Comparison
+
+### Simple Scope Tracking
+
+**File:** `chars_to_variable.rb`
+
+Tracks variable assignments within the current lexical scope. When a variable is assigned from a specific call (e.g., `.chars`), subsequent uses of that variable are checked.
+
+```ruby
+def example
+  chars = str.chars  # Tracked: chars -> .chars source
+  chars[0]           # Detected: inefficient indexing
+end
+```
+
+**Advantages:**
+- Simple implementation
+- Low overhead
+- Easy to understand and debug
+
+**Limitations:**
+- Cannot track variable aliasing (`x = chars; x[0]`)
+- Cannot track instance variables across methods
+- Scope resets on reassignment
+
+### Taint Tracking
+
+**Files:** `taint_tracking_base.rb`, `chars_to_variable_tainted.rb`
+
+Propagates metadata ("taint") through variable assignments, tracking the origin of data as it flows through the program.
+
+```ruby
+def example
+  chars = str.chars  # Taint: chars is "chars_array" from str
+  x = chars          # Propagate: x inherits taint from chars
+  y = x              # Propagate: y inherits taint from x
+  y[0]               # Detected: y is tainted with chars_array origin
+end
+```
+
+**Advantages:**
+- Tracks variable aliasing
+- Handles instance variables
+- Supports chained assignments
+- Cleaner separation of concerns
+
+**Limitations:**
+- More complex implementation
+- Higher memory usage (stores taint info per variable)
+- Cannot track across method boundaries (yet)
+
+## Detection Comparison
+
+| Scenario | Simple | Taint |
+|----------|--------|-------|
+| Direct usage: `chars[0]` | Yes | Yes |
+| Aliased: `x = chars; x[0]` | No | Yes |
+| Chained: `a = chars; b = a; b[0]` | No | Yes |
+| Instance var: `@chars[0]` | No | Yes |
+| Cross-method: `def foo; @chars[0]; end` | No | No* |
+
+*Cross-method tracking would require whole-program analysis.
+
+## TaintTrackingBase API
+
+The `TaintTrackingBase` class provides infrastructure for building taint-tracking patterns.
+
+### Subclass Requirements
+
+```ruby
+class MyPattern < TaintTrackingBase
+  self.pattern_id = :my_pattern
+  self.optimization_type = :allocation
+
+  protected
+
+  # Define what creates a taint
+  def taint_from_call(call_node)
+    return nil unless call_node.name == :dangerous_method
+
+    {
+      type: :my_taint_type,
+      source: call_node.receiver,
+      source_code: call_node.receiver&.slice,
+      origin_line: call_node.location.start_line,
+      metadata: {}
+    }
+  end
+
+  # Check for problematic uses of tainted variables
+  def check_tainted_usage(call_node, var_name, taint_info)
+    return unless taint_info.type == :my_taint_type
+
+    if call_node.name == :problematic_method
+      add_finding(call_node, message: "...")
+    end
+  end
+end
+```
+
+### Available Methods
+
+```ruby
+# Query taint status
+get_taint(var_name, scope: :local)   # Returns TaintInfo or nil
+tainted?(var_name, scope: :local)    # Returns boolean
+all_taints(scope: :local)            # Returns hash of all taints
+
+# Modify taint status (rarely needed in subclasses)
+set_taint(var_name, taint_info, scope: :local)
+clear_taint(var_name, scope: :local)
+```
+
+### TaintInfo Structure
+
+```ruby
+TaintInfo = Data.define(
+  :type,         # Symbol identifying the taint type
+  :source,       # Original AST node (e.g., receiver of .chars)
+  :source_code,  # String representation of source
+  :origin_line,  # Line number where taint originated
+  :metadata      # Hash for pattern-specific data
+)
+```
+
+## Scope Handling
+
+Both approaches handle Ruby's lexical scoping:
+
+| Construct | Scope Behavior |
+|-----------|----------------|
+| `def` | New isolated scope |
+| `class` / `module` | New isolated scope |
+| `lambda` / `->` | New isolated scope |
+| `block` | Inherits parent scope (for taint tracking) |
+
+Instance variables use a separate scope (`:instance`) that persists across blocks but resets at class/module boundaries.
+
+## When to Use Each Approach
+
+**Use Simple Scope Tracking when:**
+- Pattern only needs direct variable usage
+- Performance is critical
+- Implementation simplicity is preferred
+
+**Use Taint Tracking when:**
+- Pattern involves variable aliasing
+- Instance variables need tracking
+- Data flow through assignments matters
+- Building on existing taint infrastructure
+
+## Future Directions
+
+1. **Cross-method tracking**: Track instance variable taints across method definitions
+2. **Escape analysis**: Detect when tainted values escape the current scope
+3. **Conditional tracking**: Handle `if` branches that may or may not taint
+4. **LLM review layer**: Use language models to filter false positives from complex patterns

data/lib/hone/patterns/array_compact.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Hone
+  module Patterns
+    # Pattern: array.reject { |x| x.nil? } -> array.compact
+    #          array.select { |x| !x.nil? } -> array.compact
+    #
+    # compact is implemented in C and optimized for removing nil values.
+    # Using reject/select with a block for nil checking is slower and less clear.
+    class ArrayCompact < Base
+      self.pattern_id = :array_compact
+      self.optimization_type = :cpu
+
+      def visit_call_node(node)
+        super
+
+        return unless %i[reject select].include?(node.name)
+        return unless block_attached?(node)
+
+        block = node.block
+        return unless block.is_a?(Prism::BlockNode)
+
+        if node.name == :reject && reject_nil_pattern?(block)
+          add_finding(
+            node,
+            message: "Use `.compact` instead of `.reject { |x| x.nil? }` for optimized nil removal",
+            speedup: "Uses optimized C implementation"
+          )
+        elsif node.name == :select && select_not_nil_pattern?(block)
+          add_finding(
+            node,
+            message: "Use `.compact` instead of `.select { |x| !x.nil? }` for optimized nil removal",
+            speedup: "Uses optimized C implementation"
+          )
+        end
+      end
+
+      private
+
+      # Detects: { |x| x.nil? }
+      def reject_nil_pattern?(block)
+        return false unless single_block_param?(block)
+
+        body = block.body
+        return false unless body.is_a?(Prism::StatementsNode)
+        return false unless body.body.size == 1
+
+        statement = body.body.first
+        nil_check_on_param?(statement, block_param_name(block))
+      end
+
+      # Detects: { |x| !x.nil? }
+      def select_not_nil_pattern?(block)
+        return false unless single_block_param?(block)
+
+        body = block.body
+        return false unless body.is_a?(Prism::StatementsNode)
+        return false unless body.body.size == 1
+
+        statement = body.body.first
+        negated_nil_check_on_param?(statement, block_param_name(block))
+      end
+
+      def single_block_param?(block)
+        params = block.parameters
+        return false unless params.is_a?(Prism::BlockParametersNode)
+
+        parameters = params.parameters
+        return false unless parameters.is_a?(Prism::ParametersNode)
+        return false unless parameters.requireds.size == 1
+        return false unless parameters.optionals.empty?
+        return false unless parameters.rest.nil?
+        return false unless parameters.keywords.empty?
+
+        true
+      end
+
+      def block_param_name(block)
+        block.parameters.parameters.requireds.first.name
+      end
+
+      # Checks if statement is: param.nil?
+      def nil_check_on_param?(statement, param_name)
+        return false unless statement.is_a?(Prism::CallNode)
+        return false unless statement.name == :nil?
+        return false unless statement.arguments.nil?
+
+        receiver = statement.receiver
+        return false unless receiver.is_a?(Prism::LocalVariableReadNode)
+
+        receiver.name == param_name
+      end
+
+      # Checks if statement is: !param.nil?
+      def negated_nil_check_on_param?(statement, param_name)
+        # Check for !(...) pattern
+        return false unless statement.is_a?(Prism::CallNode)
+        return false unless statement.name == :!
+        return false unless statement.receiver
+
+        nil_check_on_param?(statement.receiver, param_name)
+      end
+    end
+  end
+end

data/lib/hone/patterns/array_include_set.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Hone
+  module Patterns
+    # Pattern: array.include?(x) -> consider Set for repeated lookups
+    #
+    # Array#include? is O(n) for each lookup.
+    # If performing repeated lookups, converting to Set gives O(1) lookups.
+    class ArrayIncludeSet < Base
+      self.pattern_id = :array_include_set
+      self.optimization_type = :cpu
+
+      def visit_call_node(node)
+        super
+
+        # Look for: .include?(x) with one argument
+        return unless node.name == :include?
+        return unless node.arguments&.arguments&.size == 1
+
+        # Skip if receiver is a known hash method chain (handled by hash_keys_include)
+        receiver = node.receiver
+        if receiver.is_a?(Prism::CallNode)
+          return if receiver.name == :keys || receiver.name == :values
+        end
+
+        add_finding(
+          node,
+          message: "Consider using Set instead of Array#include? for repeated lookups",
+          speedup: "O(1) vs O(n) for repeated lookups"
+        )
+      end
+    end
+  end
+end

data/lib/hone/patterns/base.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Hone
+  # Pattern matchers for detecting optimization opportunities in Ruby AST.
+  #
+  # Each pattern class inherits from Base and implements visit_* methods
+  # to detect specific anti-patterns using Prism's visitor interface.
+  #
+  # @example Creating a custom pattern
+  #   class MyPattern < Base
+  #     self.pattern_id = :my_pattern
+  #     self.optimization_type = :cpu
+  #
+  #     def visit_call_node(node)
+  #       super
+  #       # detection logic here
+  #     end
+  #   end
+  module Patterns
+    @registered = []
+
+    class << self
+      attr_reader :registered
+
+      def register(pattern_class)
+        @registered << pattern_class
+      end
+    end
+
+    class Base < Prism::Visitor
+      def self.inherited(subclass)
+        Patterns.register(subclass)
+      end
+      class << self
+        attr_accessor :pattern_id, :optimization_type
+
+        def scope
+          @scope || :ruby
+        end
+
+        attr_writer :scope
+      end
+
+      def self.scan_file(path)
+        result = Prism.parse_file(path)
+        pattern = new(path)
+        result.value.accept(pattern)
+        pattern.findings
+      end
+
+      def initialize(file_path)
+        @file_path = file_path
+        @findings = []
+      end
+
+      attr_reader :findings
+
+      def add_finding(node, message:, speedup: nil)
+        @findings << Finding.new(
+          file: @file_path,
+          line: node.location.start_line,
+          column: node.location.start_column,
+          pattern_id: self.class.pattern_id,
+          optimization_type: self.class.optimization_type,
+          source: :hone,
+          message: message,
+          speedup: speedup,
+          code: node.location.slice
+        )
+      end
+
+      protected
+
+      def block_attached?(call_node)
+        call_node.block.is_a?(Prism::BlockNode) ||
+          call_node.block.is_a?(Prism::BlockArgumentNode)
+      end
+
+      def with_context(variable, value)
+        previous = instance_variable_get(variable)
+        instance_variable_set(variable, value)
+        yield
+      ensure
+        instance_variable_set(variable, previous)
+      end
+    end
+  end
+end