hone 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c35d339dc059e423c261e29acd55d76091c09e94cbd1b945eb5c6436b79909ad
+  data.tar.gz: 48ed4d9d8ef4a6484e55fb4fd9d71a0cba5285aee2bc52c6436644c631cec33c
+SHA512:
+  metadata.gz: f0cd2110c5a28b7e35cb463e00a118cd63e0a9ef2ca206e4d7bb38afc76223b8c1f319a857f4e9cb788d4a29293694312f874efac0580774d0a0b922afb8e654
+  data.tar.gz: 8c2058eed3b4699e9ada63edaa316b2f3029aeb9728568bbb614ba8d521986af7b612be6eb75fc49eda7f6f3c55cc33f7ce94355764a6b73516464c2cf59eb03

data/.standard.yml

@@ -0,0 +1,8 @@
+# For available configuration options, see:
+#   https://github.com/standardrb/standard
+ruby_version: 3.1
+ignore:
+  - "test/fixtures/**/*":
+      - Style/GlobalVars
+  - "test/harness_test.rb":
+      - Style/GlobalVars

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-12-26
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Stephen Ierodiaconou
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,201 @@
+<p align="center">
+  <img src="logo.png" alt="Hone" width="200">
+</p>
+
+# Hone
+
+> **Note:** This is currently a proof of concept. APIs and output formats may change.
+
+Find Ruby performance optimizations that actually matter by combining static analysis with runtime profiling.
+
+## Example Output
+
+When run with profiling data, performance optimisation findings show their potential runtime impact:
+
+```
+Hone v0.1.0
+
+Analyzing lib/sqids.rb with profile: tmp/hone/cpu_profile.json
+────────────────────────────────────────────────────────────────────────
+
+lib/sqids.rb:69 in `Sqids#decode`
+17.5% of allocations — High impact
+
+67 │
+68 │     alphabet_chars = @alphabet.chars
+69 │     id.chars.each do |c|
+         ^^^^^^^^^^^^^^^^^^^^
+70 │       return ret unless alphabet_chars.include?(c)
+71 │     end
+
+     Use `id.each_char { ... }` instead of `chars.each` to avoid intermediate array
+
+────────────────────────────────────────────────────────────────────────
+
+lib/sqids.rb:183 in `Sqids#blocked_id?`
+13.5% of CPU — High impact
+
+181 │           id.start_with?(word) || id.end_with?(word)
+182 │         else
+183 │           id.include?(word)
+                ^^^^^^^^^^^^^^^^^
+184 │         end
+185 │       end
+
+     Consider using Set instead of Array#include? for repeated lookups
+
+────────────────────────────────────────────────────────────────────────
+
+lib/sqids.rb:104 in `Sqids#shuffle`
+3.1% of CPU — Moderate
+
+102 │     i = 0
+103 │     j = chars.length - 1
+104 │     while j.positive?
+                ^^^^^^^^^^^
+105 │       r = ((i * j) + chars[i].ord + chars[j].ord) % chars.length
+106 │       chars[i], chars[r] = chars[r], chars[i]
+
+Fix: j > 0
+     Use `> 0` instead of `.positive?` to avoid method call overhead
+
+────────────────────────────────────────────────────────────────────────
+
+Summary: 14 findings
+
+  3 high impact  (>5% of CPU or allocations)  ← fix these first
+  11 moderate  (1-5%)
+```
+
+The percentages show how much CPU time or memory allocation each method used during profiling, helping you focus on fixes that matter.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'hone', group: :development
+
+# Optional: for profiling integration
+gem 'stackprof', group: :development
+gem 'memory_profiler', group: :development
+```
+
+Or install directly:
+
+```bash
+gem install hone
+```
+
+## Quick Start
+
+```bash
+# Try it on the included examples
+hone analyze examples/
+
+# Or analyze your own code
+hone analyze lib/
+```
+
+### With Profiling (Recommended)
+
+For prioritized results, use a harness:
+
+```bash
+# Create a harness in your project
+hone init harness
+
+# Edit .hone/harness.rb to define your workload, then:
+hone profile --analyze
+```
+
+Or provide an existing StackProf profile:
+
+```bash
+hone analyze lib/ --profile stackprof.json
+```
+
+### About Impact Levels
+
+| Level | Meaning |
+|-------|---------|
+| High impact | >5% CPU or allocation - fix these first |
+| JIT issue | Hurts YJIT optimization |
+| Moderate | 1-5% impact - worth fixing |
+| Low | <1% impact - low priority |
+
+Without profiling data, findings show "Unknown" impact.
+
+## CLI Reference
+
+```bash
+# Analysis
+hone analyze FILE|DIR                    # Static analysis
+hone analyze FILE --profile STACKPROF    # With CPU correlation
+hone analyze FILE --memory-profile FILE  # With memory correlation
+
+# Profiling
+hone init harness                        # Create .hone/harness.rb template
+hone profile                             # Run harness, generate profiles
+hone profile --analyze                   # Profile and analyze in one step
+hone profile --memory                    # Include memory profiling
+
+# Output control
+--format FORMAT      # text, json, github, sarif, junit, tsv
+--top N              # Show only top N findings
+--hot-only           # Only high impact findings
+--show-cold          # Include low impact findings (hidden by default)
+--quiet / -q         # One line per finding
+--verbose / -V       # Extended output with pattern details
+
+# CI integration
+--fail-on LEVEL      # Exit non-zero for: hot, warm, any, none
+--baseline FILE      # Suppress known findings
+```
+
+## Harness
+
+The harness defines a repeatable workload for profiling:
+
+```ruby
+# .hone/harness.rb
+setup do
+  require_relative '../lib/my_gem'
+  @data = load_test_data
+end
+
+exercise iterations: 100 do
+  MyGem.process(@data)
+end
+
+teardown do
+  cleanup  # optional
+end
+```
+
+- `setup`: Runs once before profiling (load code, prepare data)
+- `exercise`: The code to profile (runs N iterations)
+- `teardown`: Cleanup after profiling (optional)
+
+## Patterns
+
+Hone detects 50+ patterns across three categories:
+
+- **CPU**: Method call overhead, loop inefficiencies
+- **Allocation**: Intermediate arrays, string allocations
+- **JIT**: Dynamic ivars, shape transitions, YJIT blockers
+
+Run `hone patterns` to list all available patterns.
+
+## Requirements
+
+- Ruby 3.1+
+- Prism (bundled with Ruby 3.3+, add `gem 'prism'` for earlier versions)
+
+## Acknowledgements
+
+Some pattern detections inspired by:
+
+- [fast-ruby](https://github.com/fastruby/fast-ruby) - Benchmarks for common Ruby idioms
+- [fasterer](https://github.com/DamirSvrtan/fasterer) - Static analysis for speed improvements
+- [rubocop-performance](https://github.com/rubocop/rubocop-performance) - Performance-focused RuboCop cops

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "standard/rake"
+
+task default: %i[test standard]

data/examples/.hone/harness.rb

@@ -0,0 +1,41 @@
+# Hone harness for example patterns
+# Run with: hone profile --analyze
+
+setup do
+  require_relative "../cpu_patterns"
+  require_relative "../allocation_patterns"
+  require_relative "../jit_patterns"
+
+  @cpu = CpuPatterns.new
+  @alloc = AllocationPatterns.new
+  @jit = JitPatterns.new
+  @data = (1..100).to_a
+  @str = "hello world" * 10
+end
+
+exercise iterations: 1000 do
+  # CPU patterns
+  @cpu.check_positive(42)
+  @cpu.count_up
+  @cpu.sum_with_index(@data)
+  @cpu.tail(@str)
+  @cpu.replace_spaces(@str)
+  @cpu.match_pattern(["abc", "123", "def"])
+
+  # Allocation patterns
+  @alloc.char_codes(@str)
+  @alloc.transform_and_filter(@data)
+  @alloc.iterate_chars("test")
+  @alloc.nested_map([1, 2, 3])
+  @alloc.total(@data)
+  @alloc.random_element(@data)
+  @alloc.smallest(@data)
+  @alloc.final_element(@data)
+  @alloc.build_string(%w[a b c d e])
+  @alloc.char_at(@str, 5)
+
+  # JIT patterns
+  @jit.set_field("test", 123)
+  @jit.get_field("test")
+  @jit.cached_value
+end

data/examples/README.md

@@ -0,0 +1,22 @@
+# Hone Examples
+
+Example files with intentional anti-patterns for testing Hone.
+
+## Quick Test
+
+```bash
+cd examples
+
+# Static analysis only
+hone analyze .
+
+# With profiling (recommended)
+hone profile --memory --analyze
+```
+
+## Files
+
+- `cpu_patterns.rb` - Method call overhead, loop inefficiencies
+- `allocation_patterns.rb` - Intermediate arrays, string allocations
+- `jit_patterns.rb` - YJIT optimization blockers
+- `.hone/harness.rb` - Profiling harness for these examples

data/examples/allocation_patterns.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+# rubocop:disable all
+# standardrb:disable all
+
+# Allocation-related patterns that Hone detects
+# NOTE: This file intentionally contains anti-patterns for testing
+
+class AllocationPatterns
+  # chars.map(&:ord) vs bytes
+  def char_codes(str)
+    str.chars.map(&:ord)  # Hone: Use `str.bytes` instead
+  end
+
+  # map.select vs filter_map
+  def transform_and_filter(arr)
+    arr.map { |x| x * 2 }.select { |x| x > 10 }  # Hone: Use `filter_map`
+  end
+
+  # chars.each vs each_char
+  def iterate_chars(str)
+    count = 0
+    str.chars.each { |c| count += 1 }  # Hone: Use `each_char`
+    count
+  end
+
+  # map.flatten vs flat_map
+  def nested_map(arr)
+    arr.map { |x| [x, x * 2] }.flatten  # Hone: Use `flat_map`
+  end
+
+  # inject(:+) vs sum
+  def total(arr)
+    arr.inject(:+)  # Hone: Use `sum`
+  end
+
+  # shuffle.first vs sample
+  def random_element(arr)
+    arr.shuffle.first  # Hone: Use `sample`
+  end
+
+  # sort.first vs min
+  def smallest(arr)
+    arr.sort.first  # Hone: Use `min`
+  end
+
+  # reverse.first vs last
+  def final_element(arr)
+    arr.reverse.first  # Hone: Use `last`
+  end
+
+  # String concatenation in loop
+  def build_string(parts)
+    result = ""
+    parts.each do |part|
+      result += part  # Hone: Use `<<` or array.join
+    end
+    result
+  end
+
+  # Variable from .chars then indexed
+  def char_at(str, i)
+    chars = str.chars  # Allocates array
+    chars[i]           # Hone: Use `str[i]` directly
+  end
+end

data/examples/cpu_patterns.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+# rubocop:disable all
+# standardrb:disable all
+
+# CPU-related patterns that Hone detects
+# NOTE: This file intentionally contains anti-patterns for testing
+
+class CpuPatterns
+  # positive? vs > 0
+  def check_positive(n)
+    n.positive?  # Hone: Use `> 0` instead
+  end
+
+  # loop vs while true
+  def count_up
+    i = 0
+    loop do  # Hone: Use `while true` for JIT optimization
+      i += 1
+      break if i > 100
+    end
+    i
+  end
+
+  # each_with_index vs manual index
+  def sum_with_index(arr)
+    total = 0
+    arr.each_with_index do |val, i|  # Hone: Consider manual indexing in hot loops
+      total += val * i
+    end
+    total
+  end
+
+  # Slice with length vs endless range
+  def tail(str)
+    str[1, str.length]  # Hone: Use `str[1..]` instead
+  end
+
+  # gsub single char vs tr
+  def replace_spaces(str)
+    str.gsub(" ", "_")  # Hone: Use `tr` for single char replacement
+  end
+
+  # Regexp in loop
+  def match_pattern(strings)
+    strings.select do |s|
+      s.match?(/\d+/)  # Hone: Extract regexp to constant
+    end
+  end
+end

data/examples/jit_patterns.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+# rubocop:disable all
+# standardrb:disable all
+
+# JIT optimization patterns that Hone detects
+# NOTE: This file intentionally contains anti-patterns for testing
+# These patterns can prevent YJIT from optimizing effectively
+
+class JitPatterns
+  # Dynamic instance_variable_set
+  def set_field(name, value)
+    instance_variable_set("@#{name}", value)  # Hone: Causes shape transitions
+  end
+
+  # Dynamic instance_variable_get
+  def get_field(name)
+    instance_variable_get("@#{name}")  # Hone: Consider explicit accessors
+  end
+
+  # Lazy ivar initialization outside initialize
+  def cached_value
+    @cached ||= expensive_computation  # Hone: Initialize in constructor
+  end
+
+  # defined? check for ivar
+  def ensure_loaded
+    @data = load_data unless defined?(@data)  # Hone: Use nil check or initialize
+  end
+
+  private
+
+  def expensive_computation
+    sleep(0.001)
+    42
+  end
+
+  def load_data
+    []
+  end
+end
+
+# RECOMMENDED: Initialize all ivars in constructor for stable object shape.
+# This allows YJIT to optimize method dispatch because the object's
+# memory layout is consistent from creation.
+class StableShape
+  def initialize
+    @cached = nil
+    @data = nil
+  end
+
+  def cached_value
+    @cached ||= expensive_computation
+  end
+
+  def data
+    @data ||= load_data
+  end
+
+  private
+
+  def expensive_computation
+    42
+  end
+
+  def load_data
+    []
+  end
+end

data/exe/hone

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "hone"
+require "hone/cli"
+
+Hone::CLI.start(ARGV)

data/lib/hone/adapters/base.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Hone
+  module Adapters
+    class Base
+      def initialize(file_path)
+        @file_path = file_path
+      end
+
+      def findings
+        raise NotImplementedError
+      end
+
+      private
+
+      def build_finding(line:, message:, pattern_id:, optimization_type: :cpu, code: nil, speedup: nil)
+        Finding.new(
+          file: @file_path,
+          line: line,
+          column: 0,
+          pattern_id: pattern_id,
+          optimization_type: optimization_type,
+          source: source_name,
+          message: message,
+          speedup: speedup,
+          code: code
+        )
+      end
+
+      def source_name
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/hone/adapters/fasterer.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Hone
+  module Adapters
+    class Fasterer < Base
+      def findings
+        return [] unless fasterer_available?
+
+        parse_output(run_fasterer)
+      rescue NotImplementedError => e
+        warn "[Hone::Adapters::Fasterer] #{e.message}"
+        []
+      end
+
+      private
+
+      def source_name
+        :fasterer
+      end
+
+      def fasterer_available?
+        _, _, status = Open3.capture3("which", "fasterer")
+        status.success?
+      end
+
+      def run_fasterer
+        stdout, _stderr, _status = Open3.capture3("fasterer", @file_path)
+        stdout
+      end
+
+      def parse_output(output)
+        raise NotImplementedError, "Fasterer output parsing not yet implemented"
+      end
+    end
+  end
+end

data/lib/hone/adapters/rubocop_performance.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "open3"
+require "json"
+
+module Hone
+  module Adapters
+    class RubocopPerformance < Base
+      def findings
+        return [] unless rubocop_available? && rubocop_performance_available?
+
+        parse_output(run_rubocop)
+      rescue JSON::ParserError => e
+        warn "[Hone::Adapters::RubocopPerformance] Failed to parse RuboCop output: #{e.message}"
+        []
+      rescue => e
+        warn "[Hone::Adapters::RubocopPerformance] #{e.message}"
+        []
+      end
+
+      private
+
+      def source_name
+        :rubocop
+      end
+
+      def rubocop_available?
+        _, _, status = Open3.capture3("which", "rubocop")
+        status.success?
+      end
+
+      def rubocop_performance_available?
+        stdout, _, status = Open3.capture3("gem", "list", "rubocop-performance")
+        status.success? && stdout.include?("rubocop-performance")
+      end
+
+      def run_rubocop
+        stdout, _stderr, _status = Open3.capture3(
+          "rubocop",
+          "--only", "Performance",
+          "--format", "json",
+          @file_path
+        )
+        stdout
+      end
+
+      def parse_output(output)
+        return [] if output.nil? || output.strip.empty?
+
+        data = JSON.parse(output)
+        files = data["files"] || []
+
+        files.flat_map do |file_data|
+          offenses = file_data["offenses"] || []
+          offenses.map do |offense|
+            build_finding(
+              line: offense.dig("location", "line") || 0,
+              message: offense["message"],
+              pattern_id: offense["cop_name"]&.to_sym || :unknown,
+              optimization_type: severity_to_optimization_type(offense["severity"]),
+              code: extract_code(offense)
+            )
+          end
+        end
+      end
+
+      def severity_to_optimization_type(severity)
+        case severity
+        when "error", "fatal"
+          :cpu
+        when "warning"
+          :cpu
+        when "convention", "refactor"
+          :allocation
+        else
+          :cpu
+        end
+      end
+
+      def extract_code(offense)
+        offense.dig("location", "source")
+      end
+    end
+  end
+end