hone 0.1.0

data/lib/hone/patterns/string_shovel.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Hone
+  module Patterns
+    # Pattern: str = str + other -> str << other
+    #
+    # When reassigning a local variable to itself plus another string,
+    # using the shovel operator (<<) avoids creating a new string object.
+    # The + operator always creates a new string, while << mutates in place.
+    #
+    # Example:
+    #   # Before - creates new string
+    #   str = str + other
+    #   str = str + "suffix"
+    #
+    #   # After - mutates in place
+    #   str << other
+    #   str << "suffix"
+    #
+    # Note: Only safe when the original string can be mutated (not frozen,
+    # not shared with other references that expect the original value).
+    #
+    # Impact: Avoids allocating a new string object
+    class StringShovel < Base
+      self.pattern_id = :string_shovel
+      self.optimization_type = :allocation
+
+      def visit_local_variable_write_node(node)
+        super
+
+        check_string_reassignment(node, node.name)
+      end
+
+      private
+
+      def check_string_reassignment(node, var_name)
+        value = node.value
+        return unless value.is_a?(Prism::CallNode)
+        return unless value.name == :+
+
+        receiver = value.receiver
+        return unless matches_variable?(receiver, var_name)
+
+        args = value.arguments&.arguments
+        return unless args&.size == 1
+        return unless likely_string?(args.first)
+
+        add_finding(
+          node,
+          message: "Use `#{var_name} << ...` instead of `#{var_name} = #{var_name} + ...` to avoid creating a new string",
+          speedup: "Avoids creating new string"
+        )
+      end
+
+      def matches_variable?(node, var_name)
+        node.is_a?(Prism::LocalVariableReadNode) && node.name == var_name
+      end
+
+      def likely_string?(node)
+        case node
+        when Prism::StringNode, Prism::InterpolatedStringNode
+          true
+        when Prism::CallNode
+          %i[to_s to_str inspect].include?(node.name)
+        when Prism::LocalVariableReadNode
+          # Could be a string, we'll suggest the optimization
+          # User can decide if it's appropriate
+          true
+        else
+          false
+        end
+      end
+    end
+  end
+end

data/lib/hone/patterns/string_start_with.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Hone
+  module Patterns
+    # Pattern: str[0] == 'x' or str.match?(/^x/) -> str.start_with?('x')
+    #
+    # Indexing at position 0 for comparison or using regex with ^ anchor
+    # is less clear and potentially slower than using start_with?.
+    #
+    # @example Bad
+    #   str[0] == 'x'
+    #   str.match?(/^foo/)
+    #
+    # @example Good
+    #   str.start_with?('x')
+    #   str.start_with?('foo')
+    class StringStartWith < Base
+      self.pattern_id = :string_start_with
+      self.optimization_type = :cpu
+
+      def visit_call_node(node)
+        super
+
+        if index_zero_comparison?(node)
+          add_finding(
+            node,
+            message: "Use `start_with?` instead of `str[0] == ...` for cleaner code",
+            speedup: "Cleaner and avoids substring/regex overhead"
+          )
+        elsif regex_start_anchor?(node)
+          add_finding(
+            node,
+            message: "Use `start_with?` instead of `match?(/^.../)` to avoid regex overhead",
+            speedup: "Cleaner and avoids substring/regex overhead"
+          )
+        end
+      end
+
+      private
+
+      # Detects: str[0] == 'x' or 'x' == str[0]
+      def index_zero_comparison?(node)
+        return false unless node.name == :==
+        return false unless node.arguments&.arguments&.size == 1
+
+        receiver = node.receiver
+        arg = node.arguments.arguments[0]
+
+        # Check receiver[0] == arg or arg == receiver[0]
+        index_at_zero?(receiver) || index_at_zero?(arg)
+      end
+
+      # Detects: str.match?(/^.../)
+      def regex_start_anchor?(node)
+        return false unless node.name == :match?
+        return false unless node.arguments&.arguments&.size == 1
+
+        arg = node.arguments.arguments[0]
+        return false unless arg.is_a?(Prism::RegularExpressionNode)
+
+        # Check if regex starts with ^ anchor
+        arg.content.start_with?("^")
+      end
+
+      # Check if node is a [] call with index 0
+      def index_at_zero?(node)
+        return false unless node.is_a?(Prism::CallNode)
+        return false unless node.name == :[]
+        return false unless node.arguments&.arguments&.size == 1
+
+        index_arg = node.arguments.arguments[0]
+        integer_zero?(index_arg)
+      end
+
+      def integer_zero?(node)
+        node.is_a?(Prism::IntegerNode) && node.value == 0
+      end
+    end
+  end
+end

data/lib/hone/patterns/taint_tracking_base.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+module Hone
+  module Patterns
+    # Base class for patterns that need to track data flow through variables.
+    #
+    # Provides "taint tracking" - the ability to mark variables with metadata
+    # about their origin and propagate that information through assignments.
+    #
+    # Subclasses should:
+    # 1. Override `taint_from_call` to mark variables when assigned from specific calls
+    # 2. Override `check_tainted_usage` to detect problematic uses of tainted variables
+    #
+    # @example Tracking .chars allocations
+    #   class CharsTracking < TaintTrackingBase
+    #     def taint_from_call(call_node)
+    #       return nil unless call_node.name == :chars
+    #       { type: :chars, source: call_node.receiver&.slice }
+    #     end
+    #
+    #     def check_tainted_usage(call_node, taint_info)
+    #       if call_node.name == :[] && taint_info[:type] == :chars
+    #         report_finding(...)
+    #       end
+    #     end
+    #   end
+    #
+    class TaintTrackingBase < Base
+      # Taint info structure
+      TaintInfo = Data.define(:type, :source, :source_code, :origin_line, :metadata) do
+        def initialize(type:, source: nil, source_code: nil, origin_line: nil, metadata: {})
+          super
+        end
+      end
+
+      def initialize(file_path)
+        super
+        @taint_scopes = []
+      end
+
+      # === Scope Management ===
+
+      def visit_def_node(node)
+        with_taint_scope { super }
+      end
+
+      def visit_block_node(node)
+        with_taint_scope(inherit: true) { super }
+      end
+
+      def visit_lambda_node(node)
+        with_taint_scope { super }
+      end
+
+      def visit_class_node(node)
+        with_taint_scope { super }
+      end
+
+      def visit_module_node(node)
+        with_taint_scope { super }
+      end
+
+      # === Variable Tracking ===
+
+      # Track local variable assignments
+      def visit_local_variable_write_node(node)
+        super
+        track_assignment(node.name, node.value, node)
+      end
+
+      # Track instance variable assignments
+      def visit_instance_variable_write_node(node)
+        super
+        track_assignment(node.name, node.value, node, scope: :instance)
+      end
+
+      # Track multiple assignment (a, b = x, y)
+      def visit_multi_write_node(node)
+        super
+        # For simplicity, clear taints for multi-assigned variables
+        node.lefts.each do |target|
+          case target
+          when Prism::LocalVariableTargetNode
+            clear_taint(target.name)
+          end
+        end
+      end
+
+      # Track call nodes for both tainting and usage checking
+      def visit_call_node(node)
+        super
+        check_tainted_call(node)
+      end
+
+      # Track variable reads (for propagation detection)
+      def visit_local_variable_read_node(node)
+        super
+        # Subclasses can override to track reads
+      end
+
+      protected
+
+      # === Override Points for Subclasses ===
+
+      # Override to define what calls create taints
+      # @param call_node [Prism::CallNode] The call being assigned
+      # @return [TaintInfo, nil] Taint info if this call should taint, nil otherwise
+      def taint_from_call(call_node)
+        nil
+      end
+
+      # Override to check if a tainted variable is being used problematically
+      # @param call_node [Prism::CallNode] The call on a tainted variable
+      # @param var_name [Symbol] The variable name
+      # @param taint_info [TaintInfo] Information about the taint
+      def check_tainted_usage(call_node, var_name, taint_info)
+        # Subclasses implement this
+      end
+
+      # === Taint Query Methods ===
+
+      # Get taint info for a variable
+      def get_taint(var_name, scope: :local)
+        case scope
+        when :local
+          current_taint_scope[:locals][var_name]
+        when :instance
+          current_taint_scope[:instance][var_name]
+        end
+      end
+
+      # Check if a variable is tainted
+      def tainted?(var_name, scope: :local)
+        !get_taint(var_name, scope: scope).nil?
+      end
+
+      # Set taint for a variable
+      def set_taint(var_name, taint_info, scope: :local)
+        case scope
+        when :local
+          current_taint_scope[:locals][var_name] = taint_info
+        when :instance
+          current_taint_scope[:instance][var_name] = taint_info
+        end
+      end
+
+      # Clear taint for a variable (e.g., on reassignment)
+      def clear_taint(var_name, scope: :local)
+        case scope
+        when :local
+          current_taint_scope[:locals].delete(var_name)
+        when :instance
+          current_taint_scope[:instance].delete(var_name)
+        end
+      end
+
+      # Get all tainted variables in current scope
+      def all_taints(scope: :local)
+        case scope
+        when :local
+          current_taint_scope[:locals].dup
+        when :instance
+          current_taint_scope[:instance].dup
+        end
+      end
+
+      private
+
+      def with_taint_scope(inherit: false)
+        new_scope = {
+          locals: {},
+          instance: (inherit && @taint_scopes.any?) ? current_taint_scope[:instance].dup : {}
+        }
+        @taint_scopes.push(new_scope)
+        yield
+      ensure
+        @taint_scopes.pop
+      end
+
+      def current_taint_scope
+        @taint_scopes.last || {locals: {}, instance: {}}
+      end
+
+      def track_assignment(var_name, value_node, assignment_node, scope: :local)
+        # If assigned from a call, check if it should be tainted
+        if value_node.is_a?(Prism::CallNode)
+          taint_info = taint_from_call(value_node)
+          if taint_info
+            # Ensure it's a TaintInfo
+            taint_info = if taint_info.is_a?(TaintInfo)
+              taint_info
+            else
+              TaintInfo.new(**taint_info)
+            end
+            set_taint(var_name, taint_info, scope: scope)
+            return
+          end
+        end
+
+        # If assigned from another variable, propagate taint
+        if value_node.is_a?(Prism::LocalVariableReadNode)
+          source_taint = get_taint(value_node.name)
+          if source_taint
+            set_taint(var_name, source_taint, scope: scope)
+            return
+          end
+        end
+
+        # Otherwise, clear any existing taint (variable reassigned to non-tainted value)
+        clear_taint(var_name, scope: scope)
+      end
+
+      def check_tainted_call(node)
+        # Check if this is a call on a tainted local variable
+        if node.receiver.is_a?(Prism::LocalVariableReadNode)
+          var_name = node.receiver.name
+          taint_info = get_taint(var_name)
+          check_tainted_usage(node, var_name, taint_info) if taint_info
+        end
+
+        # Check if this is a call on a tainted instance variable
+        if node.receiver.is_a?(Prism::InstanceVariableReadNode)
+          var_name = node.receiver.name
+          taint_info = get_taint(var_name, scope: :instance)
+          check_tainted_usage(node, var_name, taint_info) if taint_info
+        end
+      end
+    end
+  end
+end

data/lib/hone/patterns/times_map.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Hone
+  module Patterns
+    # Pattern: n.times.map { } -> Array.new(n) { }
+    #
+    # times.map creates an Enumerator then maps over it.
+    # Array.new(n) { } directly creates the array with the block values,
+    # avoiding the Enumerator overhead.
+    #
+    # Examples:
+    #   # Bad: creates Enumerator then maps
+    #   5.times.map { |i| i * 2 }
+    #   # Good: direct array creation
+    #   Array.new(5) { |i| i * 2 }
+    class TimesMap < Base
+      self.pattern_id = :times_map
+      self.optimization_type = :allocation
+
+      def visit_call_node(node)
+        super
+
+        # Look for: .map { } where receiver is .times
+        return unless node.name == :map && block_attached?(node)
+
+        receiver = node.receiver
+        return unless receiver.is_a?(Prism::CallNode)
+        return unless receiver.name == :times
+
+        add_finding(
+          node,
+          message: "Use `Array.new(n) { }` instead of `n.times.map { }` to avoid Enumerator overhead",
+          speedup: "Avoids Enumerator overhead"
+        )
+      end
+    end
+  end
+end

data/lib/hone/patterns/uniq_by.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Hone
+  module Patterns
+    # Pattern: array.map { }.uniq -> consider array.uniq { }
+    #
+    # map { }.uniq creates an intermediate array from map, then deduplicates.
+    # If deduplicating on the transformed value, uniq { } avoids the intermediate.
+    class UniqBy < Base
+      self.pattern_id = :uniq_by
+      self.optimization_type = :allocation
+
+      def visit_call_node(node)
+        super
+
+        # Look for: .uniq where receiver is .map with a block
+        return unless node.name == :uniq
+        return unless node.arguments.nil? && !block_attached?(node)
+
+        receiver = node.receiver
+        return unless receiver.is_a?(Prism::CallNode)
+        return unless receiver.name == :map && block_attached?(receiver)
+
+        add_finding(
+          node,
+          message: "Consider `.uniq { }` instead of `.map { }.uniq` if deduping on transform",
+          speedup: "May avoid intermediate array if deduping on transform"
+        )
+      end
+    end
+  end
+end

data/lib/hone/patterns/yield_vs_block.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Hone
+  module Patterns
+    # Pattern: block.call -> yield when method has &block parameter
+    #
+    # When a method accepts a block with `&block`, calling `block.call` is slower
+    # than using `yield`. The `&block` syntax converts the block to a Proc object,
+    # which has overhead. Using `yield` avoids this Proc allocation when the block
+    # is only called (not stored or passed elsewhere).
+    #
+    # Example:
+    #   # Before - allocates Proc
+    #   def process(&block)
+    #     block.call(value)
+    #   end
+    #
+    #   # After - no Proc allocation
+    #   def process
+    #     yield(value)
+    #   end
+    #
+    # Impact: Avoids Proc allocation
+    class YieldVsBlock < Base
+      self.pattern_id = :yield_vs_block
+      self.optimization_type = :cpu
+
+      def initialize(file_path)
+        super
+        @block_param_name = nil
+      end
+
+      def visit_def_node(node)
+        block_param = find_block_parameter(node.parameters)
+
+        if block_param
+          with_context(:@block_param_name, block_param) { super }
+        else
+          super
+        end
+      end
+
+      def visit_call_node(node)
+        super
+
+        return unless @block_param_name
+        return unless node.name == :call
+
+        receiver = node.receiver
+        return unless receiver.is_a?(Prism::LocalVariableReadNode)
+        return unless receiver.name == @block_param_name
+
+        add_finding(
+          node,
+          message: "Use `yield` instead of `#{@block_param_name}.call` to avoid Proc allocation",
+          speedup: "Avoids Proc allocation"
+        )
+      end
+
+      private
+
+      def find_block_parameter(params)
+        return nil unless params
+
+        block = params.block
+        return nil unless block.is_a?(Prism::BlockParameterNode)
+
+        block.name
+      end
+    end
+  end
+end

data/lib/hone/profilers/base.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Hone
+  module Profilers
+    # Shared data structure for hotspot information across all profilers
+    HotspotInfo = Data.define(:name, :file, :line, :cpu_percent, :samples)
+
+    # Shared method matching logic for profiler implementations.
+    # Provides utilities to find and match methods/frames by name and file.
+    module MethodMatching
+      private
+
+      def find_matching_frame(method_info)
+        name, file, line, end_line = extract_search_criteria(method_info)
+
+        # First try to match by line range (for allocation profilers)
+        if line && file
+          match = @frames.find do |frame|
+            next unless frame[:file] && frame[:line]
+            next unless file_matches?(frame[:file], file)
+
+            frame_line = frame[:line].to_i
+            if end_line
+              # Method has a range, check if frame line is within it
+              frame_line >= line && frame_line <= end_line
+            else
+              # Exact line match
+              frame_line == line
+            end
+          end
+          return match if match
+        end
+
+        # Fall back to name-based matching
+        @frames.find do |frame|
+          matches_method?(frame, name, file)
+        end
+      end
+
+      def extract_search_criteria(method_info)
+        case method_info
+        when String
+          [method_info, nil, nil, nil]
+        when Hash
+          extract_from_hash(method_info)
+        else
+          extract_from_object(method_info)
+        end
+      end
+
+      # Extracts name, file, line, and end_line from a Hash with symbol or string keys.
+      #
+      # @param hash [Hash] Hash containing :name/:file/:line/:end_line keys
+      # @return [Array] [name, file, line, end_line] tuple
+      #
+      def extract_from_hash(hash)
+        [
+          hash[:name] || hash["name"],
+          hash[:file] || hash["file"],
+          hash[:line] || hash["line"],
+          hash[:end_line] || hash["end_line"]
+        ]
+      end
+
+      # Extracts name, file, line, end_line from objects with method accessors (like MethodInfo).
+      #
+      # @param obj [Object] Object responding to :qualified_name/:name and optionally :file/:line/:end_line
+      # @return [Array] [name, file, line, end_line] tuple
+      #
+      def extract_from_object(obj)
+        name = if obj.respond_to?(:qualified_name)
+          obj.qualified_name
+        elsif obj.respond_to?(:name)
+          obj.name
+        else
+          obj.to_s
+        end
+
+        file = obj.respond_to?(:file) ? obj.file : nil
+        # Support both :line and :start_line for compatibility
+        line = if obj.respond_to?(:start_line)
+          obj.start_line
+        elsif obj.respond_to?(:line)
+          obj.line
+        end
+        end_line = obj.respond_to?(:end_line) ? obj.end_line : nil
+
+        [name, file, line, end_line]
+      end
+
+      def matches_method?(frame, name, file)
+        return false unless name
+
+        name_matches = method_name_matches?(frame[:name], name)
+        return name_matches unless file && name_matches
+
+        # If file is provided, also check file match
+        file_matches?(frame[:file], file)
+      end
+
+      def method_name_matches?(frame_name, search_name)
+        return false unless frame_name
+
+        # Exact match
+        return true if frame_name == search_name
+
+        # Match without class prefix (e.g., "method_name" matches "ClassName#method_name")
+        return true if frame_name.end_with?("##{search_name}")
+
+        # Match with class prefix when searching for just method name
+        frame_method = frame_name.split("#").last
+        frame_method == search_name
+      end
+
+      def file_matches?(frame_file, search_file)
+        return false unless frame_file && search_file
+
+        # Exact match or path suffix match
+        frame_file == search_file || frame_file.end_with?(search_file) || search_file.end_with?(File.basename(frame_file))
+      end
+
+      def build_hotspot_info(frame)
+        HotspotInfo.new(
+          name: frame[:name],
+          file: frame[:file],
+          line: frame[:line],
+          cpu_percent: frame[:cpu_percent],
+          samples: frame[:samples]
+        )
+      end
+    end
+
+    class Base
+      def initialize(profile_path)
+        @profile_path = profile_path
+        @data = load_profile(profile_path)
+      end
+
+      # Returns CPU percentage for a method (0.0-100.0)
+      def cpu_percent_for(method_info)
+        raise NotImplementedError
+      end
+
+      # Returns all hotspots above threshold
+      def hotspots(threshold: 1.0)
+        raise NotImplementedError
+      end
+
+      private
+
+      def load_profile(path)
+        raise Hone::Error, "Profile file not found: #{path}" unless File.exist?(path)
+
+        JSON.parse(File.read(path))
+      rescue JSON::ParserError => e
+        raise Hone::Error, "Invalid JSON in profile file #{path}: #{e.message}"
+      end
+    end
+  end
+end