metric_adapter 0.0.1

data/README.markdown

@@ -0,0 +1,58 @@
+MetricAdapter
+==============
+
+At [LiquidPlanner](http://liquidplanner.com), we wanted to build some tools to help us analyze our code.  There are a [ton of static analyzers for ruby](http://xkcd.com/927/), each providing different insightful metrics, so there's no need to write a new analyzer.  But what do you do when you want to use more than one of them? 
+
+Each analyzer takes a different configuration, and provides results in different formats.  MetricAdapter solves the latter problem by converting the results of each analyzer into a common format.
+
+Now you can take all of these wonderful libraries and combine their results without worrying about how they internally represent their metrics.
+
+Metrics
+-------
+Each metric represents a single statement about one line of code.  Flay for instance, generates reports that looks like this:
+
+    1) IDENTICAL code found in :lasgn (mass*2 = 24)
+      lib/adapters/flay_adapter.rb:26
+      lib/adapters/flog_adapter.rb:23
+
+In this case, two metrics would be generated, one per line.  This makes it easier to annotate source files, or integrate these libraries with your favorite editor (`sed`, I kid, I know we all use `notepad` these days).
+
+Each metric contains:
+
+* Metric#location – An object representing a file path and line number
+* Metric#signature – The associated method signature (_not all metrics currently have this_)
+* Metric#message – A message explaining the metric, for instance "Has no descriptive comment"
+* Metric#score – When applicable, a numeric score or rating indicating the severity
+
+Examples
+--------
+To get normalized metrics, instantiate the static analysis library of your choice, and pass it to the appropriate adapter:
+    
+    # Instantiate and configure your analyzer
+    flay = Flay.new :mass => 4 
+    flay.process(*files)
+    flay.analyze
+    
+    # Report on the adapted metrics
+    adapter = MetricAdapter::FlayAdapter.new(flay)
+    adapter.metrics.each do |m|
+      puts "#{m.location} - #{m.message}"
+    end
+
+For a full example, see `examples/report.rb` and `examples/annotate.rb`.  You can use these examples to build tools that are appropriate for your team.
+
+Supported Libraries 
+-------------------
+
+* Flay – Code duplication
+* Flog – Code complexity
+* Reek – Code smells
+
+
+Contributing
+------------
+Please do!  Take a look at the existing adapters and tests (`lib/adapters` and `test/*_adapter_test.rb`) for examples.
+
+---
+
+[Adam Sanderson](http://monkeyandcrow.com) for [LiquidPlanner](http://liquidplanner.com)

data/examples/analyzer_mixin.rb

@@ -0,0 +1,34 @@
+require 'flay'
+require 'flog'
+require 'reek'
+
+# In your actual application, you would configure each of these static
+# analyzers to match your own exacting standards.  These mostly use the 
+# defaults for each library.
+# 
+module AnalyzerMixin
+  # Generate metrics for Flay.
+  # 
+  # In this sample, we are setting the `mass` option low so that there are more
+  # results.
+  # 
+  def flay(files, mass = 4)
+    flay = Flay.new :mass => mass 
+    flay.process(*files)
+    flay.analyze
+    MetricAdapter::FlayAdapter.new(flay).metrics
+  end
+
+  # Generate flog metrics.
+  def flog(files)
+    flog = Flog.new
+    flog.flog(*files)
+    MetricAdapter::FlogAdapter.new(flog).metrics
+  end
+
+  # Generate Reek metrics.
+  def reek(files)
+    examiner = Reek::Examiner.new(files)
+    MetricAdapter::ReekAdapter.new(examiner).metrics
+  end
+end

data/examples/annotate.rb

@@ -0,0 +1,75 @@
+DIR_NAME = File.dirname(__FILE__)
+$:.unshift(DIR_NAME + '/../lib')
+
+require "metric_adapter"
+require "./#{DIR_NAME}/analyzer_mixin"
+
+#
+# This is an example of using MetricAdapter to provide a common
+# interface for Flay, Flog, and Reek's metrics to annotate a file.
+#
+
+include AnalyzerMixin
+
+COLORS = {
+  :normal    => "\033[39m",
+  :alternate => "\033[38;5;99m",
+  :faded     => "\033[90m"
+}
+
+files = ARGV.empty? ? [__FILE__] : ARGV
+
+def report_on_file(path, metrics)
+  puts "\n#{path}"
+  return if !metrics || metrics.empty?
+  
+  metrics_by_line = metrics.group_by{|m| m.location.line }
+  
+  source = IO.read(path)
+  source.lines.each_with_index do |src_line, i|
+    line_number  = i + 1 # Logical line numbers, not indices
+    src_line     = src_line.chomp # Strip newline
+    indent       = src_line.scan(/\A\s+/).first
+    line_metrics = metrics_by_line[line_number]
+
+    print_metrics(line_number, line_metrics, indent)
+    print_src(line_number, src_line)
+  end
+end
+
+def print_metrics(line_number, metrics, indent = "")
+  return unless metrics
+  
+  metrics.each do |m|
+    print_line line_number, "#{indent}#{m.message}", :alternate
+  end
+end
+
+def print_src(line_number, src_line)
+  if src_line =~ /^\s*#/
+    # Print a comment
+    print_line line_number, src_line, :faded
+  else
+    # Print a normal line
+    print_line line_number, src_line, :normal
+  end
+end
+
+def print_line(line_number, text, name)
+  formatted_number = '%5d.' % line_number
+  puts "#{color formatted_number, :faded} #{color text, name}"
+end
+
+def color(text, name)
+  "#{COLORS[name]}#{text}\033[0m"
+end
+
+# Combine metrics from all our sources (See AnalyzerMixin):
+metrics = flay(files, 16) + flog(files) + reek(files)
+
+metrics_by_path = metrics.group_by{|m| m.location.path }
+
+files.each do |path|
+  metrics = metrics_by_path[path]
+  report_on_file(path, metrics)
+end

data/examples/report.rb

@@ -0,0 +1,37 @@
+DIR_NAME = File.dirname(__FILE__)
+$:.unshift(DIR_NAME + '/../lib')
+
+require "metric_adapter"
+require "./#{DIR_NAME}/analyzer_mixin"
+
+include AnalyzerMixin
+
+#
+# This is a quick and dirty example of using MetricAdapter to provide a common
+# interface for Flay, Flog, and Reek's metrics.
+#
+
+files = ARGV.empty? ? Dir[DIR_NAME + '/../lib/**/*.rb'] : ARGV
+
+# Helper for displaying an ascii divider
+def divider(char="-")
+  char * 80
+end
+
+# Combine metrics from all our sources (See AnalyzerMixin):
+metrics = flay(files) + flog(files) + reek(files)
+
+# Group those metrics by path
+metrics_by_path = metrics.group_by{|m| m.location.path }
+
+# For each path, print out a little report.
+metrics_by_path.each do |path, metrics|
+  puts divider
+  puts path
+  puts divider
+  
+  puts "  line: message"
+  metrics.sort_by{|m| m.location }.each do |m|
+    puts "%6d: %s" % [m.location.line, m.message]
+  end
+end

data/lib/adapters/flay_adapter.rb

@@ -0,0 +1,51 @@
+module MetricAdapter
+  class FlayAdapter
+    attr_reader :flay
+  
+    def initialize(flay)
+      @flay = flay
+    end
+  
+    def metrics
+      metrics = flay.hashes.map do |hash_key, nodes|
+        nodes.permutation(2).map do |node_a, node_b|
+          create_metric(hash_key, node_a, node_b)
+        end
+      end
+      
+      metrics.flatten
+    end
+  
+    private
+  
+    def metrics_for_hash(hash_key, score)
+      nodes = flay.hashes[hash_key]
+      is_identical = 
+      
+      location = method_location(signature)
+      message  = "Flog: #{score.round(2)}"
+    
+      metric = Metric.new(location, signature, message)
+      metric.score = score
+    
+      metric
+    end
+    
+    def create_metric(hash_key, node_a, node_b)
+      is_identical = flay.identical[hash_key]
+      similarity   = is_identical ? "identical" : "similar"
+      score = flay.masses[hash_key]
+      
+      message = "Flay: #{score}, #{similarity} to #{node_location(node_b)}"
+      # TODO: generate signatures from locations
+      signature = ""
+      
+      metric = Metric.new(node_location(node_a), signature, message)
+    end
+    
+    def node_location(node)
+      Location.new(node.file, node.line)
+    end
+  end
+  
+end

data/lib/adapters/flog_adapter.rb

@@ -0,0 +1,47 @@
+module MetricAdapter
+  class FlogAdapter
+    attr_reader :flog
+  
+    def initialize(flog)
+      @flog = flog
+    end
+  
+    def metrics
+      metrics = []
+      
+      flog.each_by_score do |signature, score|
+        if locatable?(signature)
+          metrics << create_metric(signature, score)
+        end
+      end
+      
+      metrics
+    end
+  
+    private
+  
+    def create_metric(signature, score)
+      location = method_location(signature)
+      message  = "Flog: #{score.round(2)}"
+    
+      metric = Metric.new(location, signature, message)
+      metric.score = score
+    
+      metric
+    end
+  
+    def method_location(signature)
+      path = flog.method_locations[signature]
+      Location.new(path)
+    end
+    
+    # Flog will report on code that is not in a class or method,
+    # all of this top level code may be spread out across multiple
+    # files, so we can're report on that code's location.
+    def locatable?(signature)
+      !!flog.method_locations[signature]
+    end
+    
+  end
+  
+end

data/lib/adapters/reek_adapter.rb

@@ -0,0 +1,32 @@
+module MetricAdapter
+  class ReekAdapter
+    attr_reader :examiner
+  
+    def initialize(examiner)
+      @examiner = examiner
+    end
+  
+    def metrics
+      metrics = examiner.smells.map do |smell|
+        line_numbers = Array(smell.lines).uniq
+        line_numbers.map do |line|
+          create_metric(smell, line)
+        end
+      end
+      
+      metrics.flatten
+    end
+  
+    private
+  
+    def create_metric(smell, line)
+      location  = Location.new(smell.source, line)
+      message   = "#{smell.message.capitalize} (#{smell.subclass})"
+      signature = smell.context
+
+      Metric.new(location, signature, message)
+    end
+
+  end
+  
+end

data/lib/location.rb

@@ -0,0 +1,36 @@
+module MetricAdapter
+  class Location
+    attr_reader :path, :line
+    
+    def initialize(combined_path, line = 0)
+      @path, @line = parse_path(combined_path || '')
+      @line ||= line
+    end
+    
+    def to_s
+      "#{path}:#{line}"
+    end
+    
+    def <=>(other)
+      [path,line] <=> [other.path, other.line]
+    end
+    
+    private
+    
+    def parse_path(path)
+      path = path.strip
+      
+      if has_line_number?(path)
+        *path_chunks, line = path.split(':')
+        [path_chunks.join(':'), line.to_i]
+      else
+        [path,nil]
+      end
+    end
+    
+    def has_line_number?(path)
+      !!(path =~ /\:\d+\s*$/)
+    end
+    
+  end
+end

data/lib/metric.rb

@@ -0,0 +1,29 @@
+module MetricAdapter
+  
+  # A normalized representation of a code metric.
+  class Metric
+    
+    # Location where this metric applies
+    attr_accessor :location
+    
+    # Associated class and method signature
+    attr_accessor :signature
+    
+    # Message indicating the issue being reported
+    attr_accessor :message
+    
+    # Optional score for for the metric indicating severity
+    # A score is not normalized across analyzers
+    attr_accessor :score
+    
+    # Create an instance of Metric.
+    # `location` is expected to be a `Location` instance
+    def initialize(location, signature,  message)
+      @location  = location
+      @signature = signature
+      @message   = message
+      @score     = 0
+    end
+  
+  end
+end

data/lib/metric_adapter.rb

@@ -0,0 +1,8 @@
+require 'metric'
+require 'location'
+
+module MetricAdapter
+  autoload :FlogAdapter, 'adapters/flog_adapter'
+  autoload :FlayAdapter, 'adapters/flay_adapter'
+  autoload :ReekAdapter, 'adapters/reek_adapter'
+end

data/test/flay_adapter_test.rb

@@ -0,0 +1,53 @@
+require "minitest/autorun"
+require "metric_adapter"
+
+require "flay"
+
+class FlayAdapterTest < MiniTest::Unit::TestCase
+  include MetricAdapter
+  
+  def test_empty_flay
+    flay    = Flay.new
+    adapter = FlayAdapter.new(flay)
+    
+    assert_equal [], adapter.metrics
+  end
+  
+  def test_flay_adapts_locations
+    adapter  = flay_self
+    flay = adapter.flay
+    # For each set of similar nodes, it should generate all the permutations (nodes choose 2)
+    expected_count = flay.hashes.map{|h, nodes| nodes ** 2}.inject{|n,m| n+m }
+    
+    assert_equal expected_count, adapter.metrics.length, "Each set of similar nodes should generate n^2 metrics"
+  end
+  
+  def test_flay_adapts_locations
+    adapter  = flay_self
+    metric   = adapter.metrics.first
+    location = metric.location
+    
+    assert_equal __FILE__, location.path, "Should reference this file"
+    assert location.line != 0, "Line numbers should be captured (line:0 should not show up in flog)"
+  end
+  
+  def test_flay_messages
+    adapter  = flay_self
+    metric   = adapter.metrics.first
+    message  = metric.message
+    
+    assert message =~ /flay/i,   "Should reference flay: #{message.inspect}"
+    assert message =~ /#{Regexp.escape __FILE__}:\d+/, "Should reference the a path: #{message.inspect}"
+  end
+  
+  private
+  
+  def flay_self
+    flay = Flay.new :mass => 2
+    flay.process(__FILE__)
+    flay.analyze
+    
+    FlayAdapter.new(flay)
+  end
+  
+end

data/test/flog_adapter_test.rb

@@ -0,0 +1,69 @@
+require "minitest/autorun"
+require "metric_adapter"
+
+require "flog"
+
+class FlogAdapterTest < MiniTest::Unit::TestCase
+  include MetricAdapter
+  
+  def test_empty_flog
+    flog    = Flog.new
+    adapter = FlogAdapter.new(flog)
+    
+    assert_equal [], adapter.metrics
+  end
+  
+  def test_flogging_adapts_locations
+    adapter  = flog_self
+    metric   = adapter.metrics.first
+    location = metric.location
+    
+    assert_equal __FILE__, location.path, "Should reference this file"
+    assert location.line != 0, "Line numbers should be captured (line:0 should not show up in flog)"
+  end
+  
+  def test_flogging_messages
+    adapter  = flog_self
+    metric   = adapter.metrics.first
+    message  = metric.message
+    
+    assert message =~ /flog/i, "Should reference flog: #{message.inspect}"
+    assert message =~ /\d+/,  "Should reference the score: #{message.inspect}"
+  end
+  
+  def test_ignoring_unlocatable_metrics
+    flog  = Flog.new
+    flog.flog_ruby top_level_sample, "sample.rb"
+    flog.calculate_total_scores 
+    
+    adapter = FlogAdapter.new(flog)
+    metrics = adapter.metrics
+    
+    assert metrics.empty?, "Flog should not attach location information to top level source"
+  end
+  
+  private
+  def flog_self
+    flog = Flog.new
+    flog.flog(__FILE__)
+    
+    FlogAdapter.new(flog)
+  end
+  
+  def top_level_sample
+    <<-RUBY
+      # Some good meaningless floggable source outside the scope of a method
+      if xs.any?{|x| x ? true : false} && x.length > 3 && x.length < 9
+        xs.each do |x|
+          (x+1).times{|xp| report(xp / 2)}
+          yield x-1
+        end
+        if xs.length % 2 == 0 
+          puts xs.length % 4 == 0 ? 1 : 0
+        end
+      end
+      
+      puts xs.join(", ")
+    RUBY
+  end
+end

data/test/location_test.rb

@@ -0,0 +1,49 @@
+require "minitest/autorun"
+require "metric_adapter"
+
+class LocationTest < MiniTest::Unit::TestCase
+  include MetricAdapter
+  
+  def test_creating_a_location_with_line_number 
+    path = "./test"
+    line = 7
+    location = Location.new(path, 7)
+    
+    assert_equal path, location.path
+    assert_equal line, location.line
+  end
+  
+  def test_creating_a_location_with_no_number
+    path = "./test"
+    location = Location.new(path)
+    
+    assert_equal path, location.path
+    assert_equal 0, location.line
+  end
+  
+  def test_creating_a_location_with_embedded_line_number
+    path = "./test"
+    line = 17
+    location = Location.new("#{path}:#{line}")
+    
+    assert_equal path, location.path
+    assert_equal line, location.line
+  end
+  
+  def test_retains_colons
+    path = "yes:we_have_no_banannas"
+    line = 17
+    location = Location.new("#{path}:#{line}")
+    
+    assert_equal path, location.path
+    assert_equal line, location.line
+  end
+  
+  def test_nil_path
+    location = Location.new(nil)
+    
+    assert_equal "", location.path
+    assert_equal 0,  location.line
+  end
+    
+end

data/test/reek_adapter_test.rb

@@ -0,0 +1,55 @@
+require "minitest/autorun"
+require "metric_adapter"
+
+require "reek"
+
+class ReekAdapterTest < MiniTest::Unit::TestCase
+  SAMPLE_PATH = 'dirty.rb'
+  
+  include MetricAdapter
+  
+  def test_empty_examiner
+    examiner = Reek::Examiner.new([])
+    adapter  = ReekAdapter.new(examiner)
+    
+    assert_equal [], adapter.metrics
+  end
+   
+  def test_examiner_adapts_locations
+    adapter  = examine_sample
+    metric   = adapter.metrics.first
+    location = metric.location
+    
+    assert_equal SAMPLE_PATH, location.path, "Should have included the path"
+    assert location.line > 0, "Should have a non zero line number"
+  end
+  
+  def test_examiner_returns_metrics_for_each_line_of_each_smell
+    adapter     = examine_sample
+    metrics     = adapter.metrics
+    total_lines = adapter.examiner.smells.inject(0){|sum, s| sum + s.lines.length}
+    
+    assert_equal total_lines, metrics.length, "Should have included a metric per line, per smell"
+  end
+
+  private
+  
+  def examine_sample
+    examiner = Reek::Examiner.new(sample)
+    ReekAdapter.new(examiner)
+  end
+  
+  def sample
+    Reek::Source::SourceCode.new(<<-SAMPLE, SAMPLE_PATH)
+      # Reek Sample Code
+      class Dirty
+        def a
+          puts @s.title
+          @s = fred.map {|x| x.each {|key| key += 3}}
+          puts @s.title
+        end
+      end
+    SAMPLE
+  end
+  
+end

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification 
+name: metric_adapter
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- Adam Sanderson
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2013-06-25 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: Provides a common interface for using metrics generated by tools such as Flog, Flay, and Reek.
+email: netghost@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.markdown
+files: 
+- lib/adapters/flay_adapter.rb
+- lib/adapters/flog_adapter.rb
+- lib/adapters/reek_adapter.rb
+- lib/location.rb
+- lib/metric.rb
+- lib/metric_adapter.rb
+- examples/analyzer_mixin.rb
+- examples/annotate.rb
+- examples/report.rb
+- test/flay_adapter_test.rb
+- test/flog_adapter_test.rb
+- test/location_test.rb
+- test/reek_adapter_test.rb
+- README.markdown
+has_rdoc: true
+homepage: https://github.com/adamsanderson/metric_adapter
+licenses: 
+- MIT
+post_install_message: 
+rdoc_options: 
+- --main
+- README.markdown
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Common interface for multiple static analyzers metrics.
+test_files: []
+