kefka 0.0.1

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt

data/Gemfile

@@ -0,0 +1,6 @@
+source "http://rubygems.org"
+
+group :development do
+  gem "rspec"
+  gem "jeweler"
+end

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2012 Reginald Tan
+
+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

@@ -0,0 +1,50 @@
+== Kefka
+
+A tool for understanding unfamiliar codebases and 3rd party libraries. It shows you callgraphs for different execution paths of a program.
+
+== Installation
+
+`gem install kefka`
+
+== Usage
+
+From the command line ,
+
+`kefka filename.rb`
+
+Examples are provided under the examples directory of kefka gem
+
+`kefka /path_to_examples_dir_of_kefka/sample1.rb`
+
+== Guinea Pigs
+
+1. Rack ( lots of procs/lambdas usage, understand middleware)
+2. Rails/Thin/WEbrick ( understand full request response cycle )
+3. Pry
+4. EventMachine ( reactor scheduler, threadpool, defer )
+5. Celluloid
+
+== Related Papers
+
+http://relo.csail.mit.edu/documentation/relo-vlhcc06.pdf
+http://dmrussell.net/CHI2010/docs/p2503.pdf
+
+== Useful Links
+
+https://github.com/ruby/ruby/blob/trunk/test/ruby/test_settracefunc.rb
+
+== Contributing to kefka
+
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
+* Fork the project.
+* Start a feature/bugfix branch.
+* Commit and push until you are happy with your contribution.
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+== Copyright
+
+Copyright (c) 2012 Reginald Tan. See LICENSE.txt for
+further details.
+

data/README.rdoc

@@ -0,0 +1,19 @@
+= kefka
+
+Description goes here.
+
+== Contributing to kefka
+ 
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
+* Fork the project.
+* Start a feature/bugfix branch.
+* Commit and push until you are happy with your contribution.
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+== Copyright
+
+Copyright (c) 2012 Reginald Tan. See LICENSE.txt for
+further details.
+

data/Rakefile

@@ -0,0 +1,43 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "kefka"
+  gem.homepage = "http://github.com/redgetan/kefka"
+  gem.license = "MIT"
+  gem.summary = %Q{A tool for reading an unfamiliar codebase }
+  gem.description = %Q{ It traces the execution path of a program and displays the source code of each method call in the callgraph }
+  gem.email = "redge.tan@gmail.com"
+  gem.authors = ["Reginald Tan"]
+  # dependencies defined in Gemfile
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+require 'rdoc/task'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "kefka #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/TODO

@@ -0,0 +1,49 @@
+== TODO
+
+1st Iteration
+
+method graph
+  has name of method
+  should display all method calls that resulted from invoking the given method
+  should display dynamic methods (metaprogrammed via instance_eval, class_eval)
+
+code box (node)
+  needs
+    method_call via (id, klass, file, lineno)
+    method_source via (file, lineno) - use 'method_source' gem
+
+  display
+    text
+
+  has source_code of a method definition
+  has line numbers
+  has filename of source_code
+  has values of local variables
+  each function should link to another code box
+  self must have parent codebox unless its main
+
+trace
+  can step forward and backward line execution
+  can show value of a variable if mouse hovers over it
+  can show all variables being affected during line execution
+  must highlight variables being changed during line execution
+
+filter
+  can filter out code initialization line execution
+    Class#inherited, Module#method_added
+  can filter out display of certain variables
+    only belonging to current file where line execution is happening
+    only ones where its changing
+
+visualization
+  Dendrogram - http://mbostock.github.com/d3/ex/cluster.html
+  Dynamic Node-Link tree - http://bl.ocks.org/999346
+  Interactive Tree - http://bl.ocks.org/1061834
+
+edge cases
+  what if method has multiple definitions (overriden )
+  for outputing local variables specified by a line, what if it's in a loop (i.e executed 10000 times)
+    maybe - do not output everything (just first 10 and last 10 to see the pattern)
+          - if the user really wants to see everything, he has to specify granurality cmd line option
+  what if there's a binding.pry in the code
+

data/VERSION

@@ -0,0 +1 @@
+0.0.1

data/bin/kefka

@@ -0,0 +1,18 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.unshift("#{File.expand_path(File.dirname(__FILE__))}/../lib")
+
+require 'kefka'
+require 'pp'
+
+if ARGV.count < 1
+  puts "Usage: kefka [path_to_file]"
+  exit
+end
+
+path = ARGV[0]
+file = File.open(path)
+
+Kefka.trace(file, :callgraph_handler)
+Kefka.display
+

data/examples/sample1.rb

@@ -0,0 +1,28 @@
+class Displayer
+  def initialize(out)
+    @out = out
+  end
+
+  def puts(val)
+    @out.puts val
+  end
+end
+
+def hello
+  num = init
+  x = 4
+  x = x * 2
+  display = Displayer.new($stdout)
+  display.puts "Hello #{num}"
+end
+
+def init
+  a = 1 + rand(9)
+  (0..3).each do |x|
+    a = a + x
+  end
+  a
+end
+
+hello
+

data/examples/trace_specific_lines.rb

@@ -0,0 +1,18 @@
+set_trace_func proc { |event, file, line, id, binding, classname|
+   printf "%8s %s:%-2d %10s %8s\n", event, file, line, id, classname
+   set_trace_func nil if line == 10
+}
+
+def fuck
+  x = 1
+  x = x + 3
+
+  (1..10).each do |x|
+    x
+  end
+
+end
+
+fuck
+
+

data/kefka.gemspec

@@ -0,0 +1,59 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = "kefka"
+  s.version = "0.0.1"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Reginald Tan"]
+  s.date = "2012-07-14"
+  s.description = " It traces the execution path of a program and displays the source code of each method call in the callgraph "
+  s.email = "redge.tan@gmail.com"
+  s.executables = ["kefka"]
+  s.extra_rdoc_files = [
+    "LICENSE.txt",
+    "README",
+    "README.rdoc",
+    "TODO"
+  ]
+  s.files = [
+    ".document",
+    "Gemfile",
+    "LICENSE.txt",
+    "README",
+    "README.rdoc",
+    "Rakefile",
+    "VERSION",
+    "bin/kefka",
+    "examples/sample1.rb",
+    "examples/trace_specific_lines.rb",
+    "kefka.gemspec",
+    "lib/kefka.rb",
+    "test/helper.rb",
+    "test/test_kefka.rb"
+  ]
+  s.homepage = "http://github.com/redgetan/kefka"
+  s.licenses = ["MIT"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = "1.8.10"
+  s.summary = "A tool for reading an unfamiliar codebase"
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<rspec>, [">= 0"])
+      s.add_development_dependency(%q<jeweler>, [">= 0"])
+    else
+      s.add_dependency(%q<rspec>, [">= 0"])
+      s.add_dependency(%q<jeweler>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<rspec>, [">= 0"])
+    s.add_dependency(%q<jeweler>, [">= 0"])
+  end
+end
+

data/lib/kefka.rb

@@ -0,0 +1,122 @@
+module Kefka
+
+  @@values = {}
+  @@method_source = {}
+
+  class << self
+
+    def get_values_of_locals_from_binding(binding)
+      locals = binding.eval("local_variables")
+      locals.inject({}) do |result,l|
+        val = binding.eval(l.to_s)
+        val = begin
+                # deep copy
+                Marshal.load(Marshal.dump(val)) if val
+              rescue TypeError
+                "_unknown_"
+              end
+
+        result.merge!({ l => val })
+        result
+      end
+    end
+
+    # Things to IGNORE
+    # 1. loading of rubygems/libraries
+    def callgraph_handler(event, file, line, id, binding, classname)
+      # do not trace current file (TODO: and anything in this library)
+      return if file == __FILE__
+      case event
+      when "call"
+        # mark the start of method call
+
+        # key must be uniquely identifiable -
+        # Class methodname is not enough
+        # perhaps include:
+        #   1. line
+        #   2. file
+        key = "#{classname}_#{id}"
+        @@method_source[key] = [file, caller[1], line]
+      when "line"
+      when "return"
+        key = "#{classname}_#{id}"
+        @@method_source[key] << line if @@method_source[key]
+      else
+        # do nothing
+      end
+    rescue Exception => e
+      puts "#{e.message} from  --  #{e.backtrace.join("\n")}"
+    end
+
+    def locals_values_handler(event, file, line, id, binding, classname)
+
+      return if file == __FILE__
+
+      case event
+      when "call"
+        #puts "Entering method #{classname} - #{id}"
+      when "line"
+        # variables that should not be tracked
+        # 1. anything in current lib
+        # 2. all local variables that are in TOP LEVEL BINDING before tracing
+        #     - but these variables may be overwritten by the traced program,
+        #       excluding them would mean not displaying certain relevant
+        #       vars in that program
+        key = "#{file}_#{line}".to_sym
+        @@values[key] = get_values_of_locals_from_binding(binding)
+      else
+        # do nothing
+      end
+    end
+
+    def start(handler)
+      set_trace_func method(handler).to_proc
+    end
+
+    def stop
+      set_trace_func nil
+    end
+
+    def trace(file, handler = :callgraph_handler)
+      puts "\nTracing Execution using #{handler}...\n\n"
+      start(handler)
+      file.rewind if file.eof?
+      code = file.read
+      eval(code, TOPLEVEL_BINDING, file.path, 1)
+      stop
+    end
+
+    def method_graph
+      @@method_source
+    end
+
+    def display
+      puts "\n==== Generating Method Callgraph...\n\n"
+      @@method_source.each do |meth,props|
+        puts
+        puts meth
+        puts
+
+        file, parent_caller, start_line, finish_line = props
+
+        File.open(file) { |f|
+          (start_line - 1).times { f.readline }
+
+          code = ""
+          (finish_line - start_line + 1).times {
+            code << f.readline
+          }
+          puts code
+        }
+
+        puts
+      end
+    end
+
+    def values
+      @@values
+    end
+
+  end
+
+end

data/test/helper.rb

@@ -0,0 +1,18 @@
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'test/unit'
+require 'shoulda'
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'kefka'
+
+class Test::Unit::TestCase
+end

data/test/test_kefka.rb

@@ -0,0 +1,7 @@
+require 'helper'
+
+class TestKefka < Test::Unit::TestCase
+  should "probably rename this file and start testing for real" do
+    flunk "hey buddy, you should probably rename this file and start testing for real"
+  end
+end

metadata

@@ -0,0 +1,91 @@
+--- !ruby/object:Gem::Specification
+name: kefka
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Reginald Tan
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-07-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &70266566895280 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70266566895280
+- !ruby/object:Gem::Dependency
+  name: jeweler
+  requirement: &70266566888960 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70266566888960
+description: ! ' It traces the execution path of a program and displays the source
+  code of each method call in the callgraph '
+email: redge.tan@gmail.com
+executables:
+- kefka
+extensions: []
+extra_rdoc_files:
+- LICENSE.txt
+- README
+- README.rdoc
+- TODO
+files:
+- .document
+- Gemfile
+- LICENSE.txt
+- README
+- README.rdoc
+- Rakefile
+- VERSION
+- bin/kefka
+- examples/sample1.rb
+- examples/trace_specific_lines.rb
+- kefka.gemspec
+- lib/kefka.rb
+- test/helper.rb
+- test/test_kefka.rb
+- TODO
+homepage: http://github.com/redgetan/kefka
+licenses:
+- MIT
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: 972812171248094550
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: A tool for reading an unfamiliar codebase
+test_files: []